From 43173294d1351ba96cabead62f61d0d422de5380 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Mon, 13 Apr 2026 16:25:08 -0700 Subject: [PATCH 01/38] Document self-serve post creation restrictions (reply summon requirement, cashtag limit) --- x-api/posts/manage-tweets/integrate.mdx | 17 +++++++++++++++++ x-api/posts/manage-tweets/introduction.mdx | 8 ++++++++ 2 files changed, 25 insertions(+) diff --git a/x-api/posts/manage-tweets/integrate.mdx b/x-api/posts/manage-tweets/integrate.mdx index 140f5506b..e0e62b317 100644 --- a/x-api/posts/manage-tweets/integrate.mdx +++ b/x-api/posts/manage-tweets/integrate.mdx @@ -48,6 +48,23 @@ To enable OAuth 2.0 in your App, you must enable it in your's App's authenticati To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must have a [developer account]/resources/fundamentals/developer-portal), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. +### Post creation restrictions (self-serve) + +The following restrictions apply to self-serve (Pay Per Use) API customers only. Enterprise API customers are not subject to these limits. + +**Reply restrictions** + +Replies via the API are only permitted if the replying account has been explicitly summoned by the original post's author. This means one of the following must be true: + +- The original author @mentions the replying user/account in their post. +- The original author quotes a post from the replying user/account. + +If neither condition is met, the reply request will be rejected. + +**Cashtag limit** + +Posts created via the API are limited to a maximum of 1 cashtag (e.g. `$TICKER`) per post. Requests that include more than 1 cashtag will be rejected. + ### Rate limits Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](https://developer.x.com/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. diff --git a/x-api/posts/manage-tweets/introduction.mdx b/x-api/posts/manage-tweets/introduction.mdx index 7ecf4875c..a7e2faa30 100644 --- a/x-api/posts/manage-tweets/introduction.mdx +++ b/x-api/posts/manage-tweets/introduction.mdx @@ -48,6 +48,10 @@ curl -X POST "https://api.x.com/2/tweets" \ -d '{"text": "Hello from the API!"}' ``` + +**Self-serve customers:** Posts created via the API are limited to a maximum of 1 cashtag per post. + + ### Reply to a Post ```bash @@ -62,6 +66,10 @@ curl -X POST "https://api.x.com/2/tweets" \ }' ``` + +**Self-serve customers:** Replies are only permitted if the original post's author has explicitly summoned the replying account by @mentioning them or quoting one of their posts. + + ### Quote a Post ```bash From baad50681abd45bb5d3e2025f2df659b73d2f322 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Tue, 14 Apr 2026 17:25:46 +0000 Subject: [PATCH 02/38] Update documentation with latest OpenAPI spec --- openapi.json | 59 +++++++++++++++++++ ...delete-x-activity-subscriptions-by-ids.mdx | 3 + 2 files changed, 62 insertions(+) create mode 100644 x-api/activity/delete-x-activity-subscriptions-by-ids.mdx diff --git a/openapi.json b/openapi.json index 8c2298f32..427972f26 100644 --- a/openapi.json +++ b/openapi.json @@ -490,6 +490,65 @@ } }, "/2/activity/subscriptions" : { + "delete" : { + "security" : [ + { + "BearerToken" : [ ] + } + ], + "tags" : [ + "Activity" + ], + "summary" : "Delete X activity subscriptions by IDs", + "description" : "Deletes multiple subscriptions for X activity events by their IDs", + "externalDocs" : { + "url" : "https://docs.x.com/x-api/activity/delete-x-activity-subscriptions-by-ids" + }, + "operationId" : "deleteActivitySubscriptionsByIds", + "parameters" : [ + { + "name" : "ids", + "in" : "query", + "description" : "Comma-separated list of subscription IDs to delete.", + "required" : true, + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ActivitySubscriptionId" + } + }, + "explode" : false, + "style" : "form" + } + ], + "responses" : { + "200" : { + "description" : "The request has succeeded.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ActivitySubscriptionDeleteResponse" + } + } + } + }, + "default" : { + "description" : "The request has failed.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + }, + "application/problem+json" : { + "schema" : { + "$ref" : "#/components/schemas/Problem" + } + } + } + } + } + }, "get" : { "security" : [ { diff --git a/x-api/activity/delete-x-activity-subscriptions-by-ids.mdx b/x-api/activity/delete-x-activity-subscriptions-by-ids.mdx new file mode 100644 index 000000000..dbbe4d42d --- /dev/null +++ b/x-api/activity/delete-x-activity-subscriptions-by-ids.mdx @@ -0,0 +1,3 @@ +--- +openapi: delete /2/activity/subscriptions +--- \ No newline at end of file From 1525766ec7eba1db3d1e9f8799ba89aef7480f22 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 14 Apr 2026 21:16:15 +0000 Subject: [PATCH 03/38] Update status.mdx for X API degradation Mintlify-Source: dashboard-editor --- status.mdx | 181 +++-------------------------------------------------- 1 file changed, 9 insertions(+), 172 deletions(-) diff --git a/status.mdx b/status.mdx index bb3c33f44..e624b6009 100644 --- a/status.mdx +++ b/status.mdx @@ -1,15 +1,18 @@ --- title: X Developer Platform Status -keywords: ["status", "API status", "system status", "uptime", "service status", "platform status", "operational status", "incidents", "incident history", "outages", "service issues", "API incidents", "system status", "downtime"] +keywords: ["status", "API status", "system status", "uptime", "service status", "platform status", "operational status"] --- - - All systems are operational. - + +We are investigating issues with X API Endpoints + + + + - -Normal + +Degraded Normal @@ -18,169 +21,3 @@ keywords: ["status", "API status", "system status", "uptime", "service status", Normal - ---- - -## Incident History -### April 2026 - - -Incident has been resolved. | **April 1, 20:15 UTC - 20:30 UTC** - - - -### March 2026 - - -Incident has been resolved. | **March 31, 20:45 UTC - 21:00 UTC** - - -Incident is ongoing. | **March 24, 02:00 UTC - Current** - - -Incident has been resolved. | **March 27, 23:20 UTC - March 28, 00:56 UTC** - - -Incident has been resolved. | **March 24, 15:20:00 UTC - 18:00:00 UTC** - - - -### February 2026 - - -Incident has been resolved. | **February 16, 18:20 UTC - 19:50 UTC** - - -Incident has been resolved. | **February 16, 13:27 UTC - 14:29 UTC** - - - -### January 2026 - - -Incident has been resolved. | **January 29, 04:00 UTC - 04:45 UTC** - - -Incident has been resolved. | **January 25, 17:00 UTC - 19:00 UTC** - - -Incident has been resolved. | **January 24, 16:48 UTC - 20:30 UTC** - - -Incident has been resolved. | **January 23, 19:25 UTC - 20:30 UTC** - - -Incident has been resolved. | **January 22, 17:30 UTC - 17:45 UTC** - - -Incident has been resolved. | **January 16, 15:39 UTC - 21:00 UTC** - - - -### December 2025 - - -Incident has been resolved. | **December 5, 7:00 UTC - October 15, 8:40 UTC** - - - -### September 2025 - - -Incident has been resolved. | **September 10, 20:30 UTC - September 11, 04:30 UTC** - - -Incident has been resolved. | **September 10, 20:30 UTC - September 10, 22:00 UTC** - - - -### August 2025 - - -Incident has been resolved. | **August 12, 01:00 UTC - August 12, 13:30 UTC** - - - -### May 2025 - - -Incident has been resolved. | **June 26, 17:00 UTC - June 26, 17:45 UTC** - - -Incident has been [resolved](https://downdetector.com/status/google/). | **June 12, 15:00 UTC - June 12, 23:00 UTC** - - -Incident has been resolved. | **May 30, 20:20 UTC - May 30, 21:00 UTC** - - -Incident has been resolved. | **May 30, 18:45 UTC - May 30, 21:00 UTC** - - -Incident has been resolved. | **May 28, 17:00 UTC - May 28, 21:41 UTC** - - -Incident has been resolved. | **May 23, 17:35 UTC - May 27, 00:00 UTC** - - -Incident has been resolved. | **May 22, 18:00 UTC** - - -Incident has been resolved. | **May 09, 05:00 - May 09, 07:00 UTC** - - - -### April 2025 - - -Incident has been resolved. | **Apr 02, 17:10 - Apr 02, 20:30 UTC** - - -Incident has been resolved. | **Apr 02, 13:09 - Apr 02, 13:51 UTC** - - - -### March 2025 - - -Incident has been resolved. | **Mar 10, 12:00 - Mar 11, 00:00 UTC** - - - -### February 2025 - - -Incident is ongoing. | **Feb 6, 00:00** - - -Incident has been resolved | **Feb 3, 17:30 - Feb 4, 01:00 UTC** - - - -### January 2025 - - - There are no past incidents. - - - -### December 2024 - - - There are no past incidents. - - - -{/* - -TEMPLATE: - -### December 2024 - - - -Incident has been resolved | **Dec 23, 03:43 - 06:22 UTC** - - - -*/} - From b342c59aa6a5c32593a40e0fb08b18ca2fb15b55 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 14 Apr 2026 14:27:27 -0700 Subject: [PATCH 04/38] Revert "Update status.mdx for X API degradation" This reverts commit 1525766ec7eba1db3d1e9f8799ba89aef7480f22. --- status.mdx | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 172 insertions(+), 9 deletions(-) diff --git a/status.mdx b/status.mdx index e624b6009..bb3c33f44 100644 --- a/status.mdx +++ b/status.mdx @@ -1,18 +1,15 @@ --- title: X Developer Platform Status -keywords: ["status", "API status", "system status", "uptime", "service status", "platform status", "operational status"] +keywords: ["status", "API status", "system status", "uptime", "service status", "platform status", "operational status", "incidents", "incident history", "outages", "service issues", "API incidents", "system status", "downtime"] --- - -We are investigating issues with X API Endpoints - - - - + + All systems are operational. + - -Degraded + +Normal Normal @@ -21,3 +18,169 @@ We are investigating issues with X API Endpoints Normal + +--- + +## Incident History +### April 2026 + + +Incident has been resolved. | **April 1, 20:15 UTC - 20:30 UTC** + + + +### March 2026 + + +Incident has been resolved. | **March 31, 20:45 UTC - 21:00 UTC** + + +Incident is ongoing. | **March 24, 02:00 UTC - Current** + + +Incident has been resolved. | **March 27, 23:20 UTC - March 28, 00:56 UTC** + + +Incident has been resolved. | **March 24, 15:20:00 UTC - 18:00:00 UTC** + + + +### February 2026 + + +Incident has been resolved. | **February 16, 18:20 UTC - 19:50 UTC** + + +Incident has been resolved. | **February 16, 13:27 UTC - 14:29 UTC** + + + +### January 2026 + + +Incident has been resolved. | **January 29, 04:00 UTC - 04:45 UTC** + + +Incident has been resolved. | **January 25, 17:00 UTC - 19:00 UTC** + + +Incident has been resolved. | **January 24, 16:48 UTC - 20:30 UTC** + + +Incident has been resolved. | **January 23, 19:25 UTC - 20:30 UTC** + + +Incident has been resolved. | **January 22, 17:30 UTC - 17:45 UTC** + + +Incident has been resolved. | **January 16, 15:39 UTC - 21:00 UTC** + + + +### December 2025 + + +Incident has been resolved. | **December 5, 7:00 UTC - October 15, 8:40 UTC** + + + +### September 2025 + + +Incident has been resolved. | **September 10, 20:30 UTC - September 11, 04:30 UTC** + + +Incident has been resolved. | **September 10, 20:30 UTC - September 10, 22:00 UTC** + + + +### August 2025 + + +Incident has been resolved. | **August 12, 01:00 UTC - August 12, 13:30 UTC** + + + +### May 2025 + + +Incident has been resolved. | **June 26, 17:00 UTC - June 26, 17:45 UTC** + + +Incident has been [resolved](https://downdetector.com/status/google/). | **June 12, 15:00 UTC - June 12, 23:00 UTC** + + +Incident has been resolved. | **May 30, 20:20 UTC - May 30, 21:00 UTC** + + +Incident has been resolved. | **May 30, 18:45 UTC - May 30, 21:00 UTC** + + +Incident has been resolved. | **May 28, 17:00 UTC - May 28, 21:41 UTC** + + +Incident has been resolved. | **May 23, 17:35 UTC - May 27, 00:00 UTC** + + +Incident has been resolved. | **May 22, 18:00 UTC** + + +Incident has been resolved. | **May 09, 05:00 - May 09, 07:00 UTC** + + + +### April 2025 + + +Incident has been resolved. | **Apr 02, 17:10 - Apr 02, 20:30 UTC** + + +Incident has been resolved. | **Apr 02, 13:09 - Apr 02, 13:51 UTC** + + + +### March 2025 + + +Incident has been resolved. | **Mar 10, 12:00 - Mar 11, 00:00 UTC** + + + +### February 2025 + + +Incident is ongoing. | **Feb 6, 00:00** + + +Incident has been resolved | **Feb 3, 17:30 - Feb 4, 01:00 UTC** + + + +### January 2025 + + + There are no past incidents. + + + +### December 2024 + + + There are no past incidents. + + + +{/* + +TEMPLATE: + +### December 2024 + + + +Incident has been resolved | **Dec 23, 03:43 - 06:22 UTC** + + + +*/} + From e4e201cc560047484edb84f07c9d168010815779 Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Tue, 14 Apr 2026 14:29:24 -0700 Subject: [PATCH 05/38] Update status.mdx Signed-off-by: tcaldwell-x --- status.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/status.mdx b/status.mdx index bb3c33f44..ffa1c66b1 100644 --- a/status.mdx +++ b/status.mdx @@ -24,6 +24,9 @@ keywords: ["status", "API status", "system status", "uptime", "service status", ## Incident History ### April 2026 + +Incident has been resolved. | **April 14, 21:00 UTC - 21:30 UTC** + Incident has been resolved. | **April 1, 20:15 UTC - 20:30 UTC** From 3cc84ce76a5c04e9b8f0e73a09a1feb6188c98b3 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Wed, 15 Apr 2026 17:24:43 +0000 Subject: [PATCH 06/38] Update documentation with latest OpenAPI spec --- openapi.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/openapi.json b/openapi.json index 427972f26..f46e81039 100644 --- a/openapi.json +++ b/openapi.json @@ -513,6 +513,8 @@ "required" : true, "schema" : { "type" : "array", + "minItems" : 1, + "maxItems" : 100, "items" : { "$ref" : "#/components/schemas/ActivitySubscriptionId" } From ef94b27d299941b650a8ce8202d8b1ff49e2a671 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Wed, 15 Apr 2026 12:35:58 -0700 Subject: [PATCH 07/38] Add bulk delete x activity endpoint --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index e159bc796..9842bd85b 100644 --- a/docs.json +++ b/docs.json @@ -840,6 +840,7 @@ "x-api/activity/activity-stream", "x-api/activity/create-x-activity-subscription", "x-api/activity/deletes-x-activity-subscription", + "x-api/activity/delete-x-activity-subscriptions-by-ids", "x-api/activity/get-x-activity-subscriptions", "x-api/activity/update-x-activity-subscription" ] From 29e2e414268ff4999fd14d3c66aade159f752afb Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Thu, 16 Apr 2026 15:14:46 -0700 Subject: [PATCH 08/38] Update PPU agreement --- developer-terms/ppu-agreement.mdx | 84 +++++++++++++------------------ 1 file changed, 36 insertions(+), 48 deletions(-) diff --git a/developer-terms/ppu-agreement.mdx b/developer-terms/ppu-agreement.mdx index 63e70a515..37beabe51 100644 --- a/developer-terms/ppu-agreement.mdx +++ b/developer-terms/ppu-agreement.mdx @@ -3,7 +3,7 @@ title: 'X Developer PPU Agreement' keywords: ["pay per use", "PPU agreement", "credits", "paid services"] --- -By clicking “Pay,” and purchasing credits for use on Paid Services, or by otherwise accessing or using any Licensed Material, you agree to the terms of our Agreement. Credits do not expire unless otherwise specified, and are not transferable or refundable except as required by law. A verified phone number is required to purchase Credits. +By clicking “Pay,” and purchasing credits for use on Paid Services, or by otherwise accessing or using any Licensed Material, you agree to the terms of our Agreement. Credits do not expire unless otherwise specified, and are not transferable or refundable except as required by law. A verified phone number is required to purchase Credits. This X Developer PPU Agreement (“**Agreement**”) is a binding legal agreement between you (referred to in this Agreement as “**you**”) and X and governs your access to and use of the Licensed Material (defined below), including any Paid Services (defined below). @@ -25,13 +25,13 @@ In this Agreement, the following definitions apply: 6\. **"Paid Service(s)”** means features or functionality of the Licensed Material that you access in exchange for deduction of credits purchased from X and deducted from your account based on your usage of calls and features as detailed on our pricing page. Unless otherwise set forth in this Agreement, all references to “Licensed Material” are intended to include the Paid Service(s). -7\. **“Payment Portal”** means the online portal made available to you to opt-in to your use of the Licensed Material, manage credit purchases for Paid Services, manage payment methods for Paid Services, enable “Auto-Recharge” (see Section VII.F) and update account information. +7\. **“Payment Portal”** means the online portal made available to you to opt-in to your use of the Licensed Material, manage credit purchases for Paid Services, manage payment methods for Paid Services, enable “Auto-Recharge” (see Section VII.F) and update account information. 8\. “**Services”** means your services, websites, applications, and other offerings (including research) that display X Content or otherwise use the Licensed Material. 9\. **“Post”** means a short-form text and multimedia-based message distributed via the X Applications. -10\. **“Pricing Schedule”** means the current list of prices per API call or action, available at [https://console.x.com/pricing](https://console.x.com/pricing), which X may update with notice. +10\. **“Pricing Schedule”** means the current list of prices per API call or action, available at [https://developer.x.com/#pricing](https://developer.x.com/#pricing). 11\. **“X”** means (a) X Corp. (865 FM 1209, Building 2, Bastrop, TX 78602, USA) if your principal place of business is outside the European Union, EFTA States, and the United Kingdom; or (b) X Internet Unlimited Company (One Cumberland Place, Fenian Street, Dublin 2, D02 AX07, Ireland) if your principal place of business is in the European Union, EFTA States, or the United Kingdom. @@ -57,31 +57,31 @@ In this Agreement, the following definitions apply: 4\. Use and display X Marks to attribute X Applications as the source of the X Content, as set forth in this Agreement. -**B. License to X.** You hereby grant X a non-exclusive, royalty free, non-transferable, and non-sublicensable revocable license to access, index, and cache by any means, including web spiders and/or crawlers, any webpage or applications on which you display X Content using [**embedded Posts**](https://developer.x.com/docs/twitter-for-websites/embedded-tweets/overview) or [**embedded timelines**](https://developer.x.com/docs/twitter-for-websites/timelines/overview). +**B. License to X.** You hereby grant X a non-exclusive, royalty free, non-transferable, and non-sublicensable revocable license to access, index, and cache by any means, including web spiders and/or crawlers, any webpage or applications on which you display X Content using [**embedded Posts** or **embedded timelines**](https://publish.x.com). **C. Incorporated Terms.** Your access to and use of the Licensed Material is also subject to, and you shall comply with, the following additional terms and policies (collectively, “**Incorporated Developer Terms**”): -1\. the [**X Developer Policy**](https://developer.x.com/developer-terms/policy); +1\. the [**X Developer Policy**](https://docs.x.com/developer-terms/policy); -2\. the [**API Restricted Use Rules**](https://developer.x.com/developer-terms/more-on-restricted-use-cases); +2\. the [**API Restricted Use Rules**](https://docs.x.com/developer-terms/restricted-use-cases); 3\. the [**X Rules**](https://help.x.com/rules-and-policies/x-rules); -4\. as it relates to your display of any of the X Content, the [**Display Requirements**](https://developer.x.com/developer-terms/display-requirements.html); +4\. as it relates to your display of any of the X Content, the [**Display Requirements**](https://docs.x.com/developer-terms/display-requirements); 5\. as it relates to your use and display of the X Marks, the [**X Brand Guidelines**](https://about.x.com/who-we-are/brand-toolkit); and 6\. as it relates to taking automated actions on your account, the [**Automation Rules**](https://help.x.com/rules-and-policies/x-automation). - **III. Restrictions on Use.** +**III. Restrictions on Use.** **A. Reverse Engineering and other Restrictions.** You shall not and you shall not attempt to (or allow others to): (a) reverse engineer, decompile, disassemble, or translate the X API or otherwise attempt to derive source code, trade secrets, or know-how in or underlying any X API or any portion thereof; (b) interfere with, modify, disrupt, or disable features or functionality of the X API or monitoring mechanisms of the X API; (c) use or access the Licensed Material to create or attempt to create a substitute or similar service or product to the X Applications; (d) sell, rent, lease, sublicense, distribute, redistribute, syndicate, create derivative works of, assign, or otherwise transfer or provide access to, in whole or in part, the Licensed Material to any third party except as expressly permitted in this Agreement; (e) provide use of the X API on a service bureau, rental or managed services basis, or permit other individuals or entities to create links to the X API or "frame" or "mirror" the X API on any other server, or wireless or Internet-based device, or otherwise make available to a third party any token, key, password, or other login credentials to the X API; (f) use the Licensed Material for any illegal, unauthorized, or other improper purpose; (g) use the Licensed Material to derive or obtain non-public information of individual X users; (h) interfere with or disrupt the integrity or performance of the X Applications, X API, or X Content contained therein; (i) remove or alter any proprietary notices or marks on the X Content; (j) attempt to gain unauthorized access to the X Applications, X API, X Content, or related systems or networks; (k) use the X API or X Content to fine-tune or train a foundation or frontier model; or (l) use X Content, by itself or bundled with third party data, or derivative analysis therefrom, to target or serve users with advertising outside of the X Applications. -**B. Commercial Use Restrictions.** If your Services are designated as ‘non-commercial,’ you shall not make Commercial Use (as defined below) of the Licensed Material. Commercial Use restrictions may not apply to officially registered non-profits or NGOs. “Commercial Use” means any use of the Licensed Material or access to the X API: (a) by or for a business (i.e. an entity whose primary purpose is to earn revenue through a product or service), or (b) as part of a product or service that is monetized (e.g., website advertising, licensing fees, in-app promotions, and sponsorships). +**B. Commercial Use Restrictions.** If your Services are designated as ‘non-commercial,’ you shall not make Commercial Use (as defined below) of the Licensed Material. Commercial Use restrictions may not apply to officially registered non-profits or NGOs. “Commercial Use” means any use of the Licensed Material or access to the X API: (a) by or for a business (i.e. an entity whose primary purpose is to earn revenue through a product or service), or (b) as part of a product or service that is monetized (e.g., website advertising, licensing fees, in-app promotions, and sponsorships). **C. No Monitoring or Measuring.** Notwithstanding anything to the contrary, you may use the following information only for non-commercial, internal purposes (e.g., to improve the functionality of the Services): (a) aggregate X Applications user metrics, such as number of active users or accounts on X Applications; (b) the responsiveness of X Applications; and (c) results, usage statistics, data, or other information (in the aggregate or otherwise) derived from analyzing, using, or regarding the performance of the X API. All such information is Confidential Information (as defined below). -**D. Rate Limits.** You will not attempt to exceed or circumvent limitations on access, calls or use of the X API ("Rate Limits"), or otherwise use the X API in a manner that exceeds reasonable request volume, constitutes excessive or abusive usage or does not otherwise comply with this Agreement. API calls and requests will deduct credits from your balance as specified in the Pricing Schedule available at [https://console.x.com/pricing](https://console.x.com/pricing). If your credit balance is insufficient for a call, requests will be denied until your credit balance is sufficient to allow deduction for that request. If you exceed or X reasonably believes that you have attempted to circumvent Rate Limits, controls to limit use of the X APIs, or are otherwise using Licensed Material in breach of this Agreement, then your ability to use the Licensed Material may be temporarily suspended or permanently blocked. X may monitor your use of the X API to improve the Licensed Material and X Applications and to ensure your compliance with this Agreement and the Incorporated Developer Terms. You agree to comply with X’s requests for additional information in connection with your usage. X may review your use of Licensed Material at any time. X’s granting of access to the X API or allowing use of Licensed Material shall be deemed to be approval of your use or a waiver or limitation on its right to required use that is compliant with this Agreement and X’s policies. No payments made are refundable, however, X may, in its discretion, permit unused Credits to be used for use that is compliant with this Agreement. +**D. Rate Limits.** You will not attempt to exceed or circumvent limitations on access, calls or use of the X API ("Rate Limits"), or otherwise use the X API in a manner that exceeds reasonable request volume, constitutes excessive or abusive usage or does not otherwise comply with this Agreement. API calls and requests will deduct credits from your balance as specified in the Pricing Schedule available at [https://developer.x.com/#pricing](https://developer.x.com/#pricing). If your credit balance is insufficient for a call, requests will be denied until your credit balance is sufficient to allow deduction for that request. If you exceed or X reasonably believes that you have attempted to circumvent Rate Limits, controls to limit use of the X APIs, or are otherwise using Licensed Material in breach of this Agreement, then your ability to use the Licensed Material may be temporarily suspended or permanently blocked. X may monitor your use of the X API to improve the Licensed Material and X Applications and to ensure your compliance with this Agreement and the Incorporated Developer Terms. You agree to comply with X’s requests for additional information in connection with your usage. X may review your use of Licensed Material at any time. X’s granting of access to the X API or allowing use of Licensed Material shall be deemed to be approval of your use or a waiver or limitation on its right to required use that is compliant with this Agreement and X’s policies. No payments made are refundable, however, X may, in its discretion, permit unused Credits to be used for use that is compliant with this Agreement. **E. Location Data.** You shall not, and you shall not allow others to, aggregate, cache, or store location data and other geographic information contained in the X Content except in conjunction with the X Content to which it is attached. You may only use location data and geographic information to identify the location tagged by the X Content. @@ -89,11 +89,11 @@ In this Agreement, the following definitions apply: **G. Security.** You will maintain the security of the X API and will not make available to any third party any token, key, password, or other login credentials to the X API. You will use industry standard security measures to prevent unauthorized access or use of any of the features and functionality of the X API, including access by viruses, worms, or any other harmful code or material. You shall keep X Content confidential and secure from unauthorized access by using industry-standard organizational and technical safeguards for such data, and with no less care than you use in connection with securing similar data you store. You will immediately notify X, consult and cooperate with investigations, assist with any required notices, and provide any information reasonably requested by X if you know of or suspect any breach of security or potential vulnerability related to the Licensed Material. You will promptly remedy such breach or potential vulnerability resulting from your access to the Licensed Material. -**H. Digital Services Act.** Notwithstanding anything to the contrary in this Agreement, to the extent you are provided access to the Licensed Material pursuant to the procedures described in Article 40 of the Digital Services Act (Regulation (EU) 2022/2065) (“DSA”), your access and use of the Licensed Material is limited solely to performing research that contributes to the detection, identification, and understanding of systemic risks in the European Union and only to the extent necessary for X to comply with its obligations under the DSA. Any such use of the Licensed Material is non-commercial as described in Section III(B) of this Agreement. You may not disclose, reproduce, license, or otherwise distribute the Licensed Material (including any derivatives thereof) that you retrieve through the X API to any person or entity outside the persons specified within your approved application unless (i) the information is disclosed to the Digital Services Coordinator or other party specifically permitted by the DSA pursuant to the “vetted researcher” status and procedures described in Article 40, or (ii) disclosure is required by law. +**H. Digital Services Act.** Notwithstanding anything to the contrary in this Agreement, to the extent you are provided access to the Licensed Material pursuant to the procedures described in Article 40 of the Digital Services Act (Regulation (EU) 2022/2065) (“DSA”), your access and use of the Licensed Material is limited solely to performing research that contributes to the detection, identification, and understanding of systemic risks in the European Union and only to the extent necessary for X to comply with its obligations under the DSA. Any such use of the Licensed Material is non-commercial as described in Section III(B) of this Agreement. You may not disclose, reproduce, license, or otherwise distribute the Licensed Material (including any derivatives thereof) that you retrieve through the X API to any person or entity outside the persons specified within your approved application unless (i) the information is disclosed to the Digital Services Coordinator or other party specifically permitted by the DSA pursuant to the “vetted researcher” status and procedures described in Article 40, or (ii) disclosure is required by law. **I. Tokens.** X may limit the number of tokens that it provides to you, including but not limited to tokens that enable access and use of functionality or features on X Applications. -**J. Usage Levels Under Agreement.** X may, at any time, review your use of its Licensed Materials under this Agreement, and suspend or terminate your use and require you to file an application for Enterprise access (as described at [**developer.x.com/en**](http://developer.x.com/en)) in order for X to consider your proposed continued use of Licensed Materials. +**J. Usage Levels Under Agreement.** X may, at any time, review your use of its Licensed Materials under this Agreement, and suspend or terminate your use and require you to file an application for Enterprise access (as described at [**https://docs.x.com/enterprise-api/introduction**](https://docs.x.com/enterprise-api/introduction)) in order for X to consider your proposed continued use of Licensed Materials. **K. Prohibition on I-Framing:** You shall not, under any circumstances, embed, display, or otherwise incorporate any Licensed Material, X Content, X API, or elements of the X Applications within an iframe, inline frame, or any similar embedding mechanism on your Services or any other platform. This prohibition is absolute and includes, but is not limited to, attempts to frame X Content for display, integration, or redistribution purposes. Violation of this clause may result in immediate termination of your Developer Agreement and your access to the Licensed Material (e.g., X API, X Data License, Developer Console) as outlined in Section VII.I. @@ -115,13 +115,11 @@ In this Agreement, the following definitions apply: You may be given access to non-public information, software, and specifications relating to the Licensed Material (“Confidential Information”). You may use Confidential Information only as necessary in exercising your rights under this Agreement. You shall not disclose Confidential Information to any third party without X’s prior written consent. You shall protect Confidential Information from unauthorized use, access, or disclosure in the same manner that you would use to protect your own confidential information of a similar nature and in no event with less than a reasonable degree of care. - - -**VII. Term; Credit Purchase Terms; Credit Deduction; Suspension, and Termination.** +**VII. Term; Credit Purchase Terms; Credit Deduction; Suspension, and Termination.** **A. Term.** The term of this Agreement will start on the date (i) you accept the terms herein or (ii) start accessing or using any of the Licensed Material, whichever is earlier, and will continue until you stop accessing and using the Licensed Material unless terminated earlier as described below. -**B. Credit Purchase Terms.** Paid Services provided as part of the Licensed Material are made available through the purchase of Credits that are deducted based on your use of features, benefits, or services, including X API usage, as described on the [https://console.x.com/pricing](https://console.x.com/pricing), Developer Site and the Payment Portal. If you purchase a Paid Service, you do so by first purchasing Credits in advance by paying the applicable fee upfront via the Payment Portal. Your credit balance will be updated after purchase and deducted as you use Paid Services. You must purchase additional credits as needed to enable access to Paid Services. Credit purchases are non-recurring unless you enable optional “Auto-Recharge” features detailed in Section VII.D. When you purchase credits via the Payment Portal, you expressly agree to the terms herein and authorize the charge. X may provide notifications for low balances. Prices for credits and deduction rates are subject to change from time to time as set forth in the Pricing Schedule. X will provide reasonable advance notice of any material change to prices, which notice may be provided via the Developer Site or Payment Portal. Price changes will apply to future purchases and deductions. If you do not agree with a price change, you may cease purchasing credits and using Paid Services. Credits do not expire unless otherwise specified, and are not transferable or refundable except as required by law. +**B. Credit Purchase Terms.** Paid Services provided as part of the Licensed Material are made available through the purchase of Credits that are deducted based on your use of features, benefits, or services, including X API usage, as described on the [https://developer.x.com/#pricing](https://developer.x.com/#pricing), Developer Site and the Payment Portal. If you purchase a Paid Service, you do so by first purchasing Credits in advance by paying the applicable fee upfront via the Payment Portal. Your credit balance will be updated after purchase and deducted as you use Paid Services. You must purchase additional credits as needed to enable access to Paid Services. Credit purchases are non-recurring unless you enable optional “Auto-Recharge” features detailed in Section VII.D. When you purchase credits via the Payment Portal, you expressly agree to the terms herein and authorize the charge. X may provide notifications for low balances. Prices for credits and deduction rates are subject to change from time to time as set forth in the Pricing Schedule. X will provide reasonable advance notice of any material change to prices, which notice may be provided via the Developer Site or Payment Portal. Price changes will apply to future purchases and deductions. If you do not agree with a price change, you may cease purchasing credits and using Paid Services. Credits do not expire unless otherwise specified, and are not transferable or refundable except as required by law. **C. Credit Deduction:** Access to Paid Services requires sufficient credits in your account. Each API call or request or use of other feature or service specified in the Pricing Schedule will deduct credits from your balance based on the rates specified in the Pricing Schedule. Deduction rates may vary, and the Pricing Schedule is subject to change. X aims to deduct credits at the time of each call or request or use of other feature or service specified in the Pricing Schedule, and to deny Paid Services for which you have an insufficient balance. In that case, you will need to purchase additional credits to enable the Paid Service. You may not maintain a negative credit balance. It is your responsibility to monitor your credit balance to help maintain access to Paid Services. @@ -129,83 +127,75 @@ You may be given access to non-public information, software, and specifications **E. Payment Terms.** X may offer payment options that vary by Paid Service, device, operating system, geographic location, or other factors, which may be updated from time to time. These payment options may include web payments using a third party payment processor (“Payment Processor”). When you access a Paid Service, you agree: (i) to pay the price listed for Credits, along with any additional amounts relating to applicable taxes, surcharges, credit card fees, bank fees, foreign transaction fees, foreign exchange fees, and currency fluctuations; and (ii) to abide by any applicable terms of service, privacy policies, or other legal agreements or restrictions (including additional age restrictions) imposed by the Payment Processor in connection with your use of a given payment method. The fee will be charged at the time of Credit purchase. It is your responsibility to monitor your Credit balance and make sure your banking, credit card, debit card, and/or other payment information is up to date, complete, and accurate at all times. If you make a payment for a Paid Service through a Payment Processor, X may receive information about your transaction such as when it was made, what platform you made the purchase on, and other information. X will not be liable for any errors made or delays by the Payment Processor, your bank, your credit card company, or any payment network. All payments to X are non-refundable except as otherwise expressly provided in this Agreement or as required by law. -**F. Optional Auto-Recharge Feature.** You may opt in to an “auto-recharge” feature via the Developer Console, authorizing X to automatically charge your saved payment method a user-selected amount between $10 and $100 when your credit balance falls below the threshold set in the auto-recharge tool (typically $5, unless otherwise indicated in the auto-recharge tool), with charges including the applicable taxes and fees for that amount as per Section VII.E; you may modify or disable this feature at any time through the Payment Portal, and by enabling it, you consent to X, via its third-party Payment Processor, charging the selected amount each time the threshold is met, though failed charges (e.g., due to an invalid payment method) will prevent credit additions. Enabling auto-recharge does not guarantee uninterrupted access to Paid Services. You remain responsible for monitoring your credit balance, regardless of notifications X may provide for low balances or auto-recharge events, and auto-recharge charges are non-refundable except as required by law. +**F. Optional Auto-Recharge Feature.** You may opt in to an “auto-recharge” feature via the Developer Console, authorizing X to automatically charge your saved payment method a user-selected amount when your credit balance falls below the threshold set in the auto-recharge tool, with charges including the applicable taxes and fees for that amount as per Section VII.E; you may modify or disable this feature at any time through the Payment Portal, and by enabling it, you consent to X, via its third-party Payment Processor, charging the selected amount each time the threshold is met, though failed charges (e.g., due to an invalid payment method) will prevent credit additions. Enabling auto-recharge does not guarantee uninterrupted access to Paid Services. You remain responsible for monitoring your credit balance, regardless of notifications X may provide for low balances or auto-recharge events, and auto-recharge charges are non-refundable except as required by law. -**D. Taxes and fees.** All fees exclude any and all taxes and similar fees now in force, enacted, or imposed in the future on the transaction, delivery of the Licensed Material, or the delivery of the X Content including any sales, use or value added taxes, goods and services tax, consumption tax, customs duties, tariffs, or similar charges. These taxes may include but are not limited to, VAT, GST, sales tax, withholding tax, and any other applicable taxes but exclude taxes solely based on X’s net income. You are responsible for the payment of all such taxes, duties, and charges and any related penalties and interest arising from the payment of such amounts. In addition, a surcharge may be charged to recover costs associated with Digital Services Tax ("DST") or similar jurisdiction-specific taxes or regulatory fees incurred by X in certain jurisdictions. This surcharge will appear as a separate line item on your invoice, where applicable, and will be calculated as a percentage of applicable charges as determined by X in its sole discretion. X may adjust this surcharge at any time, without prior notice, in response to increased tax or fee rates or related administrative costs. Depending on your location, X may be responsible for collecting and reporting information related to transaction taxes arising from your purchase of Paid Services. You grant X permission to provide your account and personal information to relevant tax authorities to fulfill our tax collection and reporting obligations. +**D. Taxes and fees.** All fees exclude any and all taxes and similar fees now in force, enacted, or imposed in the future on the transaction, delivery of the Licensed Material, or the delivery of the X Content including any sales, use or value added taxes, goods and services tax, consumption tax, customs duties, tariffs, or similar charges. These taxes may include but are not limited to, VAT, GST, sales tax, withholding tax, and any other applicable taxes but exclude taxes solely based on X’s net income. You are responsible for the payment of all such taxes, duties, and charges and any related penalties and interest arising from the payment of such amounts. In addition, a surcharge may be charged to recover costs associated with Digital Services Tax ("DST") or similar jurisdiction-specific taxes or regulatory fees incurred by X in certain jurisdictions. This surcharge will appear as a separate line item on your invoice, where applicable, and will be calculated as a percentage of applicable charges as determined by X in its sole discretion. X may adjust this surcharge at any time, without prior notice, in response to increased tax or fee rates or related administrative costs. Depending on your location, X may be responsible for collecting and reporting information related to transaction taxes arising from your purchase of Paid Services. You grant X permission to provide your account and personal information to relevant tax authorities to fulfill our tax collection and reporting obligations. **E. Refunds and Cessation of Paid Services.** You may cease using Paid Services at any time by not making further API calls. Unused credits are non-refundable and non-transferable, with no refunds for purchased or used credits, unless required by law. CREDIT PURCHASES ARE PREPAID, NON-REFUNDABLE (UNLESS REQUIRED BY LAW). You may request a refund for unused credits only in accordance with applicable law (e.g., withdrawal rights below). All transactions are final unless you have a right to withdraw pursuant to law, such as provided below. -**1\. Withdrawal Right & Refunds for Users Living in EU or UK.** You have a legal right to withdraw from your credit purchase without giving any reason within 14 days from the date of purchase (“Withdrawal Period”). To exercise this right, you must inform X of your decision to withdraw before the Withdrawal Period expires by submitting a clear statement of withdrawal to [billing support](https://docs.x.com/forms/billing-support). If you withdraw within the Withdrawal Period and have not used any credits, X will refund the full amount paid for the credit purchase, including any applicable taxes or fees, within fourteen (14) days of receiving your withdrawal notice, using the same payment method used for the purchase, unless you expressly agree otherwise. +**1. Withdrawal Right & Refunds for Users Living in EU or UK.** You have a legal right to withdraw from your credit purchase without giving any reason within 14 days from the date of purchase (“Withdrawal Period”). To exercise this right, you must inform X of your decision to withdraw before the Withdrawal Period expires by submitting a clear statement of withdrawal to [billing support](https://docs.x.com/forms/billing-support). If you withdraw within the Withdrawal Period and have not used any credits, X will refund the full amount paid for the credit purchase, including any applicable taxes or fees, within fourteen (14) days of receiving your withdrawal notice, using the same payment method used for the purchase, unless you expressly agree otherwise. -However, you expressly acknowledge and agree that if you use any credits during the Withdrawal Period (e.g., by making API calls or requests), you waive your right to withdraw, as the Paid Services will have begun with your prior express consent and acknowledgment that your withdrawal right is lost upon such use. If you use only a portion of your purchased credits during the Withdrawal Period and then exercise your withdrawal right, X will refund the amount corresponding to the unused credits, calculated based on the Pricing Schedule available at [https://console.x.com/pricing](https://console.x.com/pricing). +However, you expressly acknowledge and agree that if you use any credits during the Withdrawal Period (e.g., by making API calls or requests), you waive your right to withdraw, as the Paid Services will have begun with your prior express consent and acknowledgment that your withdrawal right is lost upon such use. If you use only a portion of your purchased credits during the Withdrawal Period and then exercise your withdrawal right, X will refund the amount corresponding to the unused credits, calculated based on the Pricing Schedule available at [https://developer.x.com/#pricing](https://developer.x.com/#pricing). -**2\. No Withdrawal Right for Users Living in Taiwan.** If you are a consumer residing in Taiwan, you may be entitled to a seven (7) day withdrawal period for credit purchases under the Consumer Protection Act, unless you have used any credits, in which case the right to withdraw is lost. To exercise this right, you must notify X within seven (7) days from the date of purchase at [billing support](https://docs.x.com/forms/billing-support). Refunds for unused credits will be processed in accordance with applicable law. +**2. No Withdrawal Right for Users Living in Taiwan.** If you are a consumer residing in Taiwan, you may be entitled to a seven (7) day withdrawal period for credit purchases under the Consumer Protection Act, unless you have used any credits, in which case the right to withdraw is lost. To exercise this right, you must notify X within seven (7) days from the date of purchase at [billing support](https://docs.x.com/forms/billing-support). Refunds for unused credits will be processed in accordance with applicable law. **F. Credits Are Non-Transferable between X Accounts.** Each purchase of Credits applies to a single X account, meaning that your purchase will apply solely to the account you were using when you purchased the Credits and will not apply to other accounts that you may have access to or control over. If you have or control multiple accounts and you want access to Paid Services on each account, you must purchase the needed Credits on each account individually. You may not allow others to use your X account to access any Licensed Material that such person did not order. You may not purchase Credits or use any Licensed Material if you are a person with whom U.S. persons are not permitted to have dealings pursuant to economic sanctions, including, without limitation, sanctions administered by the United States Department of the Treasury's Office of Foreign Assets Control or any other applicable sanctions authority ("Prohibited Person"). This includes, without limitation, persons located in, a citizen of, or ordinarily resident in the following countries and regions: Cuba, Iran, the Crimea Region of Ukraine, North Korea and Syria. You represent and warrant that you are not a Prohibited Person. -**G. Restrictions and Obligations.** You may only purchase and use Credits and use the Licensed Material if you are legally allowed to use the Licensed Material in your country and you live in a country supported by X for the applicable Credit purchase, Paid Service or Licensed Material. X may, in its discretion, restrict the ability to access the Licensed Material or purchase Credits in certain countries. X reserves the right to modify the list of supported countries from time to time. X reserves the right to refuse sale of Credits or access to Paid Services or to cancel or discontinue the sale or use of a Paid Service or the use of any Licensed Material in its sole discretion. +**G. Restrictions and Obligations.** You may only purchase and use Credits and use the Licensed Material if you are legally allowed to use the Licensed Material in your country and you live in a country supported by X for the applicable Credit purchase, Paid Service or Licensed Material. X may, in its discretion, restrict the ability to access the Licensed Material or purchase Credits in certain countries. X reserves the right to modify the list of supported countries from time to time. X reserves the right to refuse sale of Credits or access to Paid Services or to cancel or discontinue the sale or use of a Paid Service or the use of any Licensed Material in its sole discretion. **H. Suspension.** X may suspend your use of and access to the Licensed Material immediately without notice (a) if X reasonably believes that (i) your use of the Licensed Material would cause damage to, or an inordinate burden upon, the Licensed Material, (ii) you have violated this Agreement, (iii) you create risk or possible legal exposure for X, (iv) X’s provision of the Licensed Material to you is no longer commercially viable; (b) for prolonged inactivity; (c) if X is requested or directed to do so by any competent court of law, regulatory authority, or law enforcement agency; or (d) for failure to pay for the Paid Services. X will not be liable for damages of any sort that result from any such suspension. **I. Termination.** X may terminate this Agreement for any reason at X’s sole discretion. Such early termination by X shall be effective immediately. If you violate the terms of this Agreement, X may terminate this Agreement for cause immediately upon notice to you and you will not receive a refund for any Credits. You may cancel your access to Paid Services or your use of the Licensed Material on the Developer Site. You will not be entitled to a refund of any Credits, and you will not be entitled to use of any unused Credits. Upon termination of this Agreement: (a) all licenses granted in this Agreement immediately expire and you must cease use of any Licensed Material; and (b) you shall permanently delete all Licensed Material in all forms and types of media, and copies thereof, in your possession. Upon the request of X for any reason, you will promptly (and in any event within ten (10) business days of such request) provide evidence (e.g., screenshots of deletion confirmation) of compliance with the provisions of the aforementioned subpart (b) of this Section. The parties to this Agreement will not be liable to each other for any damages resulting solely from termination of this Agreement as permitted under this Agreement. - - **VIII. Compliance Audit.** X or a mutually agreed upon third party agent subject to obligations of confidentiality will be entitled to inspect and audit any records related to the performance of this Agreement in your control or possession upon reasonable notice to you, and at a reasonable time during normal business hours, for the purpose of verifying compliance with this Agreement and the fees payable to X for the two (2) year period preceding the audit. X may exercise its audit right no more than once every twelve (12) months unless it has reasonable cause for noncompliance, and such audit shall not unreasonably interfere with your business activities. You will provide your full cooperation and assistance with such audit and provide access to all Licensed Material in your possession, applicable agreements, and records. Without limiting the generality of the foregoing, as part of the audit, X may request, and you agree to provide, a written report, signed by an authorized representative, listing your then-current deployment of the Licensed Material. You will pay X within thirty (30) business days after the completion of the audit the amount of any underpayment revealed by any such audit. In addition, if any such audit reveals an underpayment by you of five percent (5%) or more, then you will also reimburse X for the reasonable costs and expenses of such audit. The requirements of this Section will survive for one (1) year following the termination of this Agreement. -**IX. Disclaimer.** +**IX. Disclaimer.** TO THE MAXIMUM EXTENT PERMISSIBLE BY APPLICABLE LAW, THE LICENSED MATERIAL IS PROVIDED TO YOU “AS IS”, “WHERE IS”, WITH ALL FAULTS, AND X DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, AND ANY WARRANTIES OR CONDITIONS ARISING OUT OF THIS AGREEMENT, COURSE OF DEALING OR USAGE OF TRADE. X DOES NOT WARRANT THAT THE LICENSED MATERIAL OR ANY OTHER X PRODUCT OR SERVICE PROVIDED HEREUNDER WILL MEET ANY OF YOUR REQUIREMENTS OR THAT USE OF SUCH LICENSED MATERIAL OR OTHER PRODUCTS OR SERVICES WILL BE ERROR-FREE, UNINTERRUPTED, VIRUS-FREE, OR SECURE. YOU ARE RESPONSIBLE FOR YOUR USE OF THE LICENSED MATERIAL AND ANY CONTENT YOU PROVIDE. THIS DISCLAIMER OF WARRANTY MAY NOT BE VALID IN SOME JURISDICTIONS AND YOU MAY HAVE WARRANTY RIGHTS UNDER LAW WHICH MAY NOT BE WAIVED OR DISCLAIMED. -**FURTHER YOU UNDERSTAND AND AGREE THAT THE PAID SERVICES ARE PROVIDED TO YOU ON AN “AS IS” AND “AS AVAILABLE” BASIS.** +**FURTHER YOU UNDERSTAND AND AGREE THAT THE PAID SERVICES ARE PROVIDED TO YOU ON AN “AS IS” AND “AS AVAILABLE” BASIS.** **X. Indemnification.** You shall defend X against any and all proceedings, demands, claims, and suits (including without limitation product liability claims), and indemnify X from any and all liabilities, damages, and costs (including without limitation reasonable attorneys' fees) to the extent arising out of (a) your use of the Licensed Material in any manner that is inconsistent with this Agreement or (b) the performance, promotion, sale, or distribution of your Services. If X seeks indemnification or defense from you under this Section, X will promptly notify you in writing of the claim(s) brought against X for which it seeks indemnification or defense. X may assume full control of the defense of claims with legal counsel of its choice. You shall not enter into any third-party agreement that would affect the rights of X, constitute an admission of fault by X, or bind X in any manner without the prior written consent of X. If X assumes control of the defense of such claim, X shall not settle any such claim requiring payment from you without your prior written approval. - - **XI. Limitation of Liability.** -IN NO EVENT WILL X BE LIABLE TO YOU OR ANY USERS FOR ANY INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL DAMAGES OR ANY LOSS OF OR DAMAGE TO USE, DATA, BUSINESS, GOODWILL OR PROFITS ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT. IN ANY CASE, X'S AGGREGATE LIABILITY FOR ANY AND ALL CLAIMS UNDER THIS AGREEMENT WILL NOT EXCEED FIFTY DOLLARS ($50.00). THE FOREGOING LIMITATIONS, EXCLUSIONS AND DISCLAIMERS SHALL APPLY REGARDLESS OF WHETHER SUCH LIABILITY ARISES FROM ANY CLAIM BASED UPON CONTRACT, WARRANTY, TORT, STRICT LIABILITY OR OTHERWISE, AND WHETHER OR NOT X HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. IF APPLICABLE LAW PROHIBITS ANY LIMITATION ON LIABILITY HEREIN, THE PARTIES AGREE THAT THE LIMITATION WILL BE DEEMED TO HAVE BEEN MODIFIED TO CONFORM TO APPLICABLE LAW. THE PARTIES AGREE THAT THE LIMITATIONS ON LIABILITIES SET FORTH HEREIN ARE AGREED ALLOCATIONS OF RISK AND SUCH LIMITATIONS WILL APPLY NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY. - - +IN NO EVENT WILL X BE LIABLE TO YOU OR ANY USERS FOR ANY INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL DAMAGES OR ANY LOSS OF OR DAMAGE TO USE, DATA, BUSINESS, GOODWILL OR PROFITS ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT. IN ANY CASE, X'S AGGREGATE LIABILITY FOR ANY AND ALL CLAIMS UNDER THIS AGREEMENT WILL NOT EXCEED FIFTY DOLLARS (\$50.00). THE FOREGOING LIMITATIONS, EXCLUSIONS AND DISCLAIMERS SHALL APPLY REGARDLESS OF WHETHER SUCH LIABILITY ARISES FROM ANY CLAIM BASED UPON CONTRACT, WARRANTY, TORT, STRICT LIABILITY OR OTHERWISE, AND WHETHER OR NOT X HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. IF APPLICABLE LAW PROHIBITS ANY LIMITATION ON LIABILITY HEREIN, THE PARTIES AGREE THAT THE LIMITATION WILL BE DEEMED TO HAVE BEEN MODIFIED TO CONFORM TO APPLICABLE LAW. THE PARTIES AGREE THAT THE LIMITATIONS ON LIABILITIES SET FORTH HEREIN ARE AGREED ALLOCATIONS OF RISK AND SUCH LIMITATIONS WILL APPLY NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY. **XII. Agreement Updates.** X may update or amend this Agreement or any of the Incorporated Developer Terms from time to time. You will check the Developer Site regularly for updates. X will alert you of material revisions to these terms by posting the updated terms on these sites, via a service notification, or by other suitable means (e.g., via email to an email address associated with your account). The changes will not be retroactive and the most current version of this Agreement, available at the Developer Site, will govern your access to and use of the Licensed Material and any corresponding transactions. Your continued access or use of the Licensed Material will constitute binding acceptance of such updates and modifications. - - **XIII. Dispute Resolution and Class Action Waiver.** -**A. THIS SECTION APPLIES TO YOU ONLY IF YOU LIVE OUTSIDE THE EUROPEAN UNION, EFTA STATES, OR THE UNITED KINGDOM, INCLUDING IF YOU LIVE IN THE UNITED STATES. PLEASE READ THIS SECTION CAREFULLY – IT MAY SIGNIFICANTLY AFFECT YOUR LEGAL RIGHTS, INCLUDING YOUR RIGHT TO FILE A LAWSUIT IN COURT.** +**A. THIS SECTION APPLIES TO YOU ONLY IF YOU LIVE OUTSIDE THE EUROPEAN UNION, EFTA STATES, OR THE UNITED KINGDOM, INCLUDING IF YOU LIVE IN THE UNITED STATES. PLEASE READ THIS SECTION CAREFULLY – IT MAY SIGNIFICANTLY AFFECT YOUR LEGAL RIGHTS, INCLUDING YOUR RIGHT TO FILE A LAWSUIT IN COURT.** -**1\. Choice of Law and Forum Selection.** The laws of the State of Texas, excluding its choice of law provisions, will govern this Agreement and any dispute that arises between you and X, notwithstanding any other agreement between the parties to the contrary. All disputes related to this Agreement, including any disputes, claims, or controversies arising out of or relating to this Agreement, the marketing of the Licensed Material, and/or your participation in the Licensed Material will be brought exclusively in the U.S. District Court for the Northern District of Texas or state courts located in Tarrant County, Texas, United States, and you consent to personal jurisdiction in those forums and waive any objection as to inconvenient forum. Without prejudice to the foregoing, you agree that, in its sole discretion, X may bring any claim, cause of action, or dispute it has against you in any competent court in the country in which you reside that has jurisdiction and venue over the claim. +**1. Choice of Law and Forum Selection.** The laws of the State of Texas, excluding its choice of law provisions, will govern this Agreement and any dispute that arises between you and X, notwithstanding any other agreement between the parties to the contrary. All disputes related to this Agreement, including any disputes, claims, or controversies arising out of or relating to this Agreement, the marketing of the Licensed Material, and/or your participation in the Licensed Material will be brought exclusively in the U.S. District Court for the Northern District of Texas or state courts located in Tarrant County, Texas, United States, and you consent to personal jurisdiction in those forums and waive any objection as to inconvenient forum. Without prejudice to the foregoing, you agree that, in its sole discretion, X may bring any claim, cause of action, or dispute it has against you in any competent court in the country in which you reside that has jurisdiction and venue over the claim. If you are a federal, state, or local government entity in the United States using the Licensed Material in your official capacity and legally unable to accept the controlling law, jurisdiction, or venue clauses above, then those clauses do not apply to you. For such U.S. federal government entities, this Agreement and any action related thereto will be governed by the laws of the United States of America (without reference to conflict of laws) and, in the absence of federal law and to the extent permitted under federal law, the laws of the State of Texas (excluding choice of law). -**2\. YOU HAVE ONE YEAR TO BRING A CLAIM AGAINST X.** You must bring any claim against X arising out of or related to this Agreement within one (1) year after the date of the occurrence of the event or facts giving rise to the dispute unless applicable law provides that the normal statute of limitations for that claim may not be shortened by agreement. If you do not bring a claim within this period, you forever waive the right to pursue any claim or cause of action, of any kind or character, based on such events or facts, and such claims or causes of action are permanently banned and X will have no liability with respect to such claim. +**2. YOU HAVE ONE YEAR TO BRING A CLAIM AGAINST X.** You must bring any claim against X arising out of or related to this Agreement within one (1) year after the date of the occurrence of the event or facts giving rise to the dispute unless applicable law provides that the normal statute of limitations for that claim may not be shortened by agreement. If you do not bring a claim within this period, you forever waive the right to pursue any claim or cause of action, of any kind or character, based on such events or facts, and such claims or causes of action are permanently banned and X will have no liability with respect to such claim. -**3\. Class Action Waiver.** To the extent permitted by law, you also waive the right to participate as a plaintiff or class member in any purported class action, collective action, or representative action proceeding. +**3. Class Action Waiver.** To the extent permitted by law, you also waive the right to participate as a plaintiff or class member in any purported class action, collective action, or representative action proceeding. -**4\. Changes to this Section.** This Dispute Resolution Section survives the end of the relationship between you and X, including cancellation of or unsubscribing from any services or communications provided by X. +**4. Changes to this Section.** This Dispute Resolution Section survives the end of the relationship between you and X, including cancellation of or unsubscribing from any services or communications provided by X. -**5\. Injunctive Relief.** Notwithstanding the foregoing, you agree that money damages would be an inadequate remedy for X in the event of a breach or threatened breach of this Agreement protecting X's intellectual property or Confidential Information, and that in the event of such a breach or threat, X, in addition to any other remedies to which it is entitled, is entitled to preliminary or injunctive relief (including an order prohibiting you from taking actions in breach of such provisions), without the need for posting bond, and specific performance as may be appropriate. The parties agree that neither the United Nations Convention on Contracts for the International Sale of Goods nor the Uniform Computer Information Transaction Act shall apply to this Agreement, regardless of the states in which the parties do business or are incorporated. No waiver by X of any covenant or right under this Agreement will be effective unless memorialized in a writing authorized by X. +**5. Injunctive Relief.** Notwithstanding the foregoing, you agree that money damages would be an inadequate remedy for X in the event of a breach or threatened breach of this Agreement protecting X's intellectual property or Confidential Information, and that in the event of such a breach or threat, X, in addition to any other remedies to which it is entitled, is entitled to preliminary or injunctive relief (including an order prohibiting you from taking actions in breach of such provisions), without the need for posting bond, and specific performance as may be appropriate. The parties agree that neither the United Nations Convention on Contracts for the International Sale of Goods nor the Uniform Computer Information Transaction Act shall apply to this Agreement, regardless of the states in which the parties do business or are incorporated. No waiver by X of any covenant or right under this Agreement will be effective unless memorialized in a writing authorized by X. **B. THIS SECTION APPLIES TO YOU ONLY IF YOU LIVE IN THE EUROPEAN UNION, EFTA STATES, OR THE UNITED KINGDOM. PLEASE READ THIS SECTION CAREFULLY – IT MAY SIGNIFICANTLY AFFECT YOUR LEGAL RIGHTS, INCLUDING YOUR RIGHT TO FILE A LAWSUIT IN COURT.** -**1\. Choice of Law and Forum Selection.** To the extent permitted by law, all disputes related to this Agreement, including any disputes, claims, or controversies arising out of or relating to this Agreement, the marketing of the Licensed Material, and/or your participation in the Licensed Material, will be brought exclusively before a competent court in Ireland without regard to conflict of law provisions and will be governed by Irish law, notwithstanding any agreement between the parties to the contrary. Without prejudice to the foregoing, you agree that, in its sole discretion, X may bring any claim, cause of action, or dispute it has against you in any competent court in the country in which you reside that has jurisdiction and venue over the claim. +**1. Choice of Law and Forum Selection.** To the extent permitted by law, all disputes related to this Agreement, including any disputes, claims, or controversies arising out of or relating to this Agreement, the marketing of the Licensed Material, and/or your participation in the Licensed Material, will be brought exclusively before a competent court in Ireland without regard to conflict of law provisions and will be governed by Irish law, notwithstanding any agreement between the parties to the contrary. Without prejudice to the foregoing, you agree that, in its sole discretion, X may bring any claim, cause of action, or dispute it has against you in any competent court in the country in which you reside that has jurisdiction and venue over the claim. -**2\. YOU HAVE ONE YEAR TO BRING A CLAIM AGAINST X.** You must bring any claim against X arising out of or related to this Agreement within one (1) year after the date of the occurrence of the event or facts giving rise to the dispute unless applicable law provides that the normal statute of limitations for that claim may not be shortened by agreement. If you do not bring a claim within this period, you forever waive the right to pursue any claim or cause of action, of any kind or character, based on such events or facts, and such claims or causes of action are permanently banned, and X will have no liability with respect to such claim. +**2. YOU HAVE ONE YEAR TO BRING A CLAIM AGAINST X.** You must bring any claim against X arising out of or related to this Agreement within one (1) year after the date of the occurrence of the event or facts giving rise to the dispute unless applicable law provides that the normal statute of limitations for that claim may not be shortened by agreement. If you do not bring a claim within this period, you forever waive the right to pursue any claim or cause of action, of any kind or character, based on such events or facts, and such claims or causes of action are permanently banned, and X will have no liability with respect to such claim. -**3\. Class Action Waiver.** To the extent permitted by law, you also waive the right to participate as a plaintiff or class member in any purported class action, collective action, or representative action proceeding. +**3. Class Action Waiver.** To the extent permitted by law, you also waive the right to participate as a plaintiff or class member in any purported class action, collective action, or representative action proceeding. -**4\. Changes to this Section.** This Dispute Resolution section survives the end of the relationship between you and X, including cancellation of or unsubscribing from any services or communications provided by X. +**4. Changes to this Section.** This Dispute Resolution section survives the end of the relationship between you and X, including cancellation of or unsubscribing from any services or communications provided by X. -**5\. Injunctive Relief.** Notwithstanding the foregoing, you agree that money damages would be an inadequate remedy for X in the event of a breach or threatened breach of this Agreement protecting X's intellectual property or Confidential Information, and that in the event of such a breach or threat, X, in addition to any other remedies to which it is entitled (including money damages), is entitled to such preliminary or injunctive relief (including an order prohibiting you from taking actions in breach of such provisions), without the need for posting bond, and specific performance as may be appropriate. The parties agree that neither the United Nations Convention on Contracts for the International Sale of Goods nor the Uniform Computer Information Transaction Act shall apply to this Agreement regardless of the states in which the parties do business or are incorporated. No waiver by X of any covenant or right under this Agreement will be effective unless memorialized in a writing authorized by X. +**5. Injunctive Relief.** Notwithstanding the foregoing, you agree that money damages would be an inadequate remedy for X in the event of a breach or threatened breach of this Agreement protecting X's intellectual property or Confidential Information, and that in the event of such a breach or threat, X, in addition to any other remedies to which it is entitled (including money damages), is entitled to such preliminary or injunctive relief (including an order prohibiting you from taking actions in breach of such provisions), without the need for posting bond, and specific performance as may be appropriate. The parties agree that neither the United Nations Convention on Contracts for the International Sale of Goods nor the Uniform Computer Information Transaction Act shall apply to this Agreement regardless of the states in which the parties do business or are incorporated. No waiver by X of any covenant or right under this Agreement will be effective unless memorialized in a writing authorized by X. **XIV. Miscellaneous.** @@ -213,7 +203,7 @@ If you are a federal, state, or local government entity in the United States usi **B. User Protection.** Unless explicitly approved by X in writing, you shall not use, or knowingly display, distribute, or otherwise make X Content, or information derived from X Content, available for purpose of: (a) conducting or providing surveillance or gathering intelligence, including but not limited to investigating or tracking X users or X Content; (b) conducting or providing analysis or research for any unlawful or discriminatory purpose or in a manner that would be inconsistent with X users' reasonable expectations of privacy; (c) monitoring sensitive events (including but not limited to protests, rallies, or community organizing meetings); or (d) targeting, segmenting, or profiling individuals based on sensitive personal information, including their health (e.g., pregnancy), negative financial status or condition, political affiliation or beliefs, racial or ethnic origin, religious or philosophical affiliation or beliefs, sex life or sexual orientation, trade union membership, X Content relating to any alleged or actual commission of a crime, or any other sensitive categories of personal information prohibited by law. -**C. Government Use**. If you display, distribute, or otherwise make available any X Content to Users that are, or that act on behalf of, any government-related entity (each a “**Government End User**”); (a) you must apply for (or already subscribe to) an Enterprise plan (as described at [**developer.x.com/en**](https://developer.x.com/en)); (b) you shall identify all such Government End Users when submitting your use case for review to X; and (c) you shall thereafter notify X in writing of any new Government End Users or any new use cases with existing Government End Users before the Services display, distribute, or otherwise make available any X Content to a Government End User or for any new use case. X may prohibit you from making X Content available to any Government End User. You shall not use, or knowingly display, distribute, or otherwise make X Content, or information derived from X Content, available to any Government End User whose primary function or mission includes conducting surveillance or gathering intelligence. If law enforcement requests information about X or its users for purposes of an ongoing investigation, you may refer them to X’s Guidelines for Law Enforcement located at [**https://help.x.com/rules-and-policies/x-law-enforcement-support**](https://help.x.com/rules-and-policies/x-law-enforcement-support). The X API and X Content are "commercial items" as that term is defined at 48 C.F.R. 2.101, consisting of "commercial computer software" and "commercial computer software documentation" as such terms are used in 48 C.F.R. 12.212. Any use, modification, derivative, reproduction, release, performance, display, disclosure, or distribution of the X API or X Content by any government entity is prohibited except as expressly permitted by the terms of this Agreement. Additionally, any use by U.S. government entities must be in accordance with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4. If you use the X API or X Content in your official capacity as an employee or representative of a U.S. state or local government entity and you are legally unable to accept the indemnity, jurisdiction, venue, or other clauses herein, then those clauses do not apply to such entity to the extent required by law. Contractor/manufacturer is X Corp., 865 FM 1209, Building 2, Bastrop, TX 78602, USA. +**C. Government Use**. If you display, distribute, or otherwise make available any X Content to Users that are, or that act on behalf of, any government-related entity (each a “**Government End User**”); (a) you must apply for (or already subscribe to) an Enterprise plan (as described at [**https://docs.x.com/enterprise-api/introduction**](https://docs.x.com/enterprise-api/introduction)); (b) you shall identify all such Government End Users when submitting your use case for review to X; and (c) you shall thereafter notify X in writing of any new Government End Users or any new use cases with existing Government End Users before the Services display, distribute, or otherwise make available any X Content to a Government End User or for any new use case. X may prohibit you from making X Content available to any Government End User. You shall not use, or knowingly display, distribute, or otherwise make X Content, or information derived from X Content, available to any Government End User whose primary function or mission includes conducting surveillance or gathering intelligence. If law enforcement requests information about X or its users for purposes of an ongoing investigation, you may refer them to X’s Guidelines for Law Enforcement located at [**https://help.x.com/rules-and-policies/x-law-enforcement-support**](https://help.x.com/rules-and-policies/x-law-enforcement-support). The X API and X Content are "commercial items" as that term is defined at 48 C.F.R. 2.101, consisting of "commercial computer software" and "commercial computer software documentation" as such terms are used in 48 C.F.R. 12.212. Any use, modification, derivative, reproduction, release, performance, display, disclosure, or distribution of the X API or X Content by any government entity is prohibited except as expressly permitted by the terms of this Agreement. Additionally, any use by U.S. government entities must be in accordance with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4. If you use the X API or X Content in your official capacity as an employee or representative of a U.S. state or local government entity and you are legally unable to accept the indemnity, jurisdiction, venue, or other clauses herein, then those clauses do not apply to such entity to the extent required by law. Contractor/manufacturer is X Corp., 865 FM 1209, Building 2, Bastrop, TX 78602, USA. **D. Compliance with Laws; Export and Import.** Each party will comply with all applicable foreign, federal, state, and local laws, rules and regulations, including without limitation all laws relating to bribery and/or corruption. The Licensed Material is subject to U.S. export laws and may be subject to import and use laws of the country where it is delivered or used. You shall abide by these laws. Under these laws, the Licensed Material may not be sold, leased, downloaded, moved, exported, re-exported, or transferred across borders without a license, or approval from the relevant government authority, to any country or to any foreign national restricted by these laws, including countries embargoed by the U.S. Government (currently Cuba, Iran, North Korea, Northern Sudan and Syria), to any restricted or denied end-user, including but not limited to any person or entity prohibited by the U.S. Office of Foreign Assets Control, or for any restricted end-use. You shall maintain all rights and licenses that are required for your Services. @@ -223,9 +213,7 @@ If you are a federal, state, or local government entity in the United States usi **G. Entire Agreement.** This Agreement constitutes the entire understanding of the parties regarding the subject matter of this Agreement and supersedes all other agreements between the parties related to the subject matter, whether written or oral. If any provision of this Agreement is held by a court of law to be unenforceable, the remaining provisions of the Agreement will remain in effect. No waiver under this Agreement will be effective unless it is in writing and signed by the party granting the waiver. A waiver granted on one occasion will not operate as a waiver on other occasions. This Agreement does not create or imply any partnership, agency or joint venture. - - -[**DEVELOPER POLICY AND TERMS**](https://developer.x.com/developer-terms) +[**DEVELOPER POLICY AND TERMS**](https://docs.x.com/developer-terms) FOLLOW [**@XDEVELOPERS**](https://x.com/XDevelopers) From f022b667dabe69ae45ee1e683f4817cda0beb40a Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Thu, 16 Apr 2026 17:53:08 -0700 Subject: [PATCH 09/38] Update media-upload-chunked.mdx Signed-off-by: tcaldwell-x --- x-api/media/quickstart/media-upload-chunked.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-api/media/quickstart/media-upload-chunked.mdx b/x-api/media/quickstart/media-upload-chunked.mdx index 2b76c7761..0440f0c23 100644 --- a/x-api/media/quickstart/media-upload-chunked.mdx +++ b/x-api/media/quickstart/media-upload-chunked.mdx @@ -354,7 +354,7 @@ console.log(`Posted: ${response.data?.id}`); Post with media - + Full endpoint documentation From e6c5abf9eb39fb940d1def8007ee8e86724a42ed Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 21 Apr 2026 13:22:25 -0700 Subject: [PATCH 10/38] Add pricing details, Owned Read rates, and enterprise-only callouts - Add full credit consumption table to pricing.mdx (read and write operations) - Add Owned Read section: $0.001/resource for 12 self-data endpoints - Add enterprise-only warnings on follow, unfollow, like, unlike endpoints - Add quote-post enterprise-only warning on create-post endpoint - Update sliders.js cost estimator dropdown with Owned Read pricing, enterprise-only indicators, and URL post pricing note - Escape dollar signs as $ to prevent LaTeX rendering in MDX --- sliders.js | 61 +++++++++++++++++++++- x-api/getting-started/pricing.mdx | 84 +++++++++++++++++++++++++++++-- x-api/posts/create-post.mdx | 6 ++- x-api/users/follow-user.mdx | 6 ++- x-api/users/like-post.mdx | 6 ++- x-api/users/unfollow-user.mdx | 6 ++- x-api/users/unlike-post.mdx | 6 ++- 7 files changed, 164 insertions(+), 11 deletions(-) diff --git a/sliders.js b/sliders.js index 91f56cbb0..b4a559723 100644 --- a/sliders.js +++ b/sliders.js @@ -36,6 +36,20 @@ async function fetchPricingData() { return pricingDataPromise; } +// Endpoints that qualify for Owned Read pricing ($0.001/resource) +// when {id} matches the authenticated user who owns the developer app +const OWNED_READ_SLUGS = new Set([ + 'get-bookmarks', 'get-blocking', 'get-muting', 'get-pinned-lists', + 'get-posts', 'get-mentions', 'get-liked-posts', + 'get-followers', 'get-following', + 'get-owned-lists', 'get-followed-lists', 'get-list-memberships' +]); + +// Endpoints that require an Enterprise plan (not available on self-serve) +const ENTERPRISE_ONLY_SLUGS = new Set([ + 'follow-user', 'unfollow-user', 'like-post', 'unlike-post' +]); + // Build mapping from pricing types to display strings function getPricingTypeDisplayName(pricingType) { const displayMapping = { @@ -406,7 +420,7 @@ async function getPricingForType(pricingType) { return null; } -function createSliderContent(endpointName, unitCost, pricingType) { +function createSliderContent(endpointName, unitCost, pricingType, options = {}) { const maxUsage = 50000; // 50k // Determine if this is event type (per resource) or request type (per request) @@ -526,6 +540,33 @@ function createSliderContent(endpointName, unitCost, pricingType) { unitCostDiv.textContent = `Unit Cost: $${unitCost.toFixed(3)} ${unitLabel}`; container.appendChild(unitCostDiv); + // Owned Read note + if (options.ownedReadCost) { + const ownedReadNote = document.createElement('div'); + ownedReadNote.className = 'text-xs mb-2'; + ownedReadNote.style.color = '#00BA7C'; + ownedReadNote.textContent = `Owned Read price: $${options.ownedReadCost.toFixed(3)} ${unitLabel} when accessing your own data as the app owner`; + container.appendChild(ownedReadNote); + } + + // Enterprise-only warning + if (options.enterpriseOnly) { + const enterpriseNote = document.createElement('div'); + enterpriseNote.className = 'text-xs mb-2'; + enterpriseNote.style.cssText = 'color: #f59e0b; border: 1px solid rgba(245,158,11,0.3); border-radius: 6px; padding: 6px 8px;'; + enterpriseNote.textContent = 'This endpoint requires an Enterprise plan. Not available on self-serve (pay-per-use) tiers.'; + container.appendChild(enterpriseNote); + } + + // URL post pricing note + if (options.urlNote) { + const urlNote = document.createElement('div'); + urlNote.className = 'text-xs mb-2'; + urlNote.style.color = '#9ca3af'; + urlNote.textContent = 'Posts containing a URL: $0.200 per request (summoned replies remain at standard price).'; + container.appendChild(urlNote); + } + // Usage label const usageLabel = document.createElement('div'); usageLabel.className = 'flex justify-between text-sm mb-1'; @@ -665,7 +706,23 @@ async function createOrUpdateDropdown() { dropdown.style.marginTop = '0.5rem'; const endpointDisplayName = getPricingTypeDisplayName(pricingType); - const sliderContent = createSliderContent(endpointDisplayName, pricing.cost, pricingType); + + // Determine additional pricing context from the current page slug + const slugMatch = window.location.pathname.match(/\/([^\/]+)$/); + const currentSlug = slugMatch ? slugMatch[1] : ''; + const sliderOptions = {}; + + if (OWNED_READ_SLUGS.has(currentSlug)) { + sliderOptions.ownedReadCost = 0.001; + } + if (ENTERPRISE_ONLY_SLUGS.has(currentSlug)) { + sliderOptions.enterpriseOnly = true; + } + if (currentSlug === 'create-post') { + sliderOptions.urlNote = true; + } + + const sliderContent = createSliderContent(endpointDisplayName, pricing.cost, pricingType, sliderOptions); dropdown.appendChild(sliderContent); // Position the page context menu as relative for absolute dropdown positioning diff --git a/x-api/getting-started/pricing.mdx b/x-api/getting-started/pricing.mdx index db49164b5..58ef05cb7 100644 --- a/x-api/getting-started/pricing.mdx +++ b/x-api/getting-started/pricing.mdx @@ -40,6 +40,82 @@ If you are on a legacy subscription package (Basic or Pro), you can opt in to Pa --- +## Credit consumption details + +All prices are per resource fetched (reads) or per request (writes/actions). [Purchase credits](https://console.x.com) in the Developer Console. + +### Read operations + +Charged per resource returned in the response. + +| Resource | Unit Cost | +|:---------|:----------| +| **Posts: Read** | $0.005 per resource | +| **User: Read** | $0.010 per resource | +| **DM Event: Read** | $0.010 per resource | +| **Following/Followers: Read** | $0.010 per resource | +| **List: Read** | $0.005 per resource | +| **Space: Read** | $0.005 per resource | +| **Community: Read** | $0.005 per resource | +| **Note: Read** | $0.005 per resource | +| **Media: Read** | $0.005 per resource | +| **Analytics: Read** | $0.005 per resource | +| **Trend: Read** | $0.010 per resource | + +### Write operations + +Charged per request. + +| Action | Unit Cost | +|:-------|:----------| +| **Content: Create** | $0.015 per request | +| **Content: Create (with URL)** | $0.200 per request | +| **DM Interaction: Create** | $0.015 per request | +| **User Interaction: Create** | $0.015 per request | +| **Interaction: Delete** | $0.010 per request | +| **Content: Manage** | $0.005 per request | +| **List: Create** | $0.010 per request | +| **List: Manage** | $0.005 per request | +| **Bookmark** | $0.005 per request | +| **Media Metadata** | $0.005 per request | +| **Privacy: Update** | $0.010 per request | +| **Mute: Delete** | $0.005 per request | +| **Counts: Recent** | $0.005 per request | +| **Counts: All** | $0.010 per request | + + +Prices are subject to change. Current rates are always available in the [Developer Console](https://console.x.com) and on the [developer.x.com pricing page](https://developer.x.com/#pricing). + + +--- + +## Owned Reads + +Owned Reads are requests made by your own developer app for your own data (posts, bookmarks, followers, likes, lists, and more). These endpoints are priced at **$0.001 per resource** (1,000 resources for $1). + +The following endpoints qualify for Owned Read pricing when `{id}` matches the authenticated user and that user is the owner of the developer app: + +| Endpoint | Description | +|:---------|:------------| +| `GET /2/users/{id}/tweets` | Your own posts | +| `GET /2/users/{id}/mentions` | Your mentions | +| `GET /2/users/{id}/liked_tweets` | Posts you liked | +| `GET /2/users/{id}/bookmarks` | Your bookmarks | +| `GET /2/users/{id}/followers` | Your followers | +| `GET /2/users/{id}/following` | Accounts you follow | +| `GET /2/users/{id}/blocking` | Accounts you blocked | +| `GET /2/users/{id}/muting` | Accounts you muted | +| `GET /2/users/{id}/owned_lists` | Lists you own | +| `GET /2/users/{id}/followed_lists` | Lists you follow | +| `GET /2/users/{id}/list_memberships` | Lists you belong to | +| `GET /2/users/{id}/pinned_lists` | Your pinned lists | + + +Owned Reads make it significantly cheaper to build apps that work with a user's own data, such as dashboard apps, personal analytics, or account management tools. + + +--- + ## Deduplication All resources are deduplicated within a **24-hour UTC day window**. If you request and are charged for a resource (such as a Post), requesting the same resource again within that window will not incur an additional charge. @@ -71,8 +147,8 @@ Enable auto-recharge to automatically top up your credit balance and avoid servi | Setting | Description | |:--------|:------------| -| **Recharge amount** | The amount to add when auto-recharge triggers (e.g., $25) | -| **Trigger threshold** | Auto-recharge activates when your balance falls below this amount (e.g., $5) | +| **Recharge amount** | The amount to add when auto-recharge triggers (e.g., $25) | +| **Trigger threshold** | Auto-recharge activates when your balance falls below this amount (e.g., $5) | Auto-recharge requires a saved payment method set as your default. You can cancel anytime in the Developer Console or by contacting support. @@ -104,7 +180,7 @@ To receive free xAI credits, you must link your xAI team to your X developer acc ### How it works -Your cumulative spend is tracked throughout each billing cycle. As you cross spending thresholds, you unlock higher reward rates. When a new billing cycle starts, your cumulative spend resets to $0. +Your cumulative spend is tracked throughout each billing cycle. As you cross spending thresholds, you unlock higher reward rates. When a new billing cycle starts, your cumulative spend resets to $0. | Cumulative spend | Rate | |:-----------------|:-----| @@ -132,7 +208,7 @@ Suppose you make several purchases throughout a billing cycle: | | | | | | | **$1,000** | | | | **$200** | -This is the same amount you'd receive from a single $1,000 purchase—the order and size of purchases doesn't affect your total rewards. +This is the same amount you'd receive from a single $1,000 purchase—the order and size of purchases doesn't affect your total rewards. View your xAI credit balance and manage your account at [console.x.ai](https://console.x.ai). For more details on xAI API billing, see the [xAI billing documentation](https://docs.x.ai/docs/key-information/billing). diff --git a/x-api/posts/create-post.mdx b/x-api/posts/create-post.mdx index 7c8307b1c..18d2d40de 100644 --- a/x-api/posts/create-post.mdx +++ b/x-api/posts/create-post.mdx @@ -1,3 +1,7 @@ --- openapi: post /2/tweets ---- \ No newline at end of file +--- + + +Quote-posting (using the `quote_tweet_id` parameter) requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. + \ No newline at end of file diff --git a/x-api/users/follow-user.mdx b/x-api/users/follow-user.mdx index 449d74830..19db16206 100644 --- a/x-api/users/follow-user.mdx +++ b/x-api/users/follow-user.mdx @@ -1,3 +1,7 @@ --- openapi: post /2/users/{id}/following ---- \ No newline at end of file +--- + + +This endpoint requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. + \ No newline at end of file diff --git a/x-api/users/like-post.mdx b/x-api/users/like-post.mdx index e6197dc22..a6825a2af 100644 --- a/x-api/users/like-post.mdx +++ b/x-api/users/like-post.mdx @@ -1,3 +1,7 @@ --- openapi: post /2/users/{id}/likes ---- \ No newline at end of file +--- + + +This endpoint requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. + \ No newline at end of file diff --git a/x-api/users/unfollow-user.mdx b/x-api/users/unfollow-user.mdx index fad80620a..f1c1aa5ec 100644 --- a/x-api/users/unfollow-user.mdx +++ b/x-api/users/unfollow-user.mdx @@ -1,3 +1,7 @@ --- openapi: delete /2/users/{source_user_id}/following/{target_user_id} ---- \ No newline at end of file +--- + + +This endpoint requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. + \ No newline at end of file diff --git a/x-api/users/unlike-post.mdx b/x-api/users/unlike-post.mdx index 41a1df715..c29de6a20 100644 --- a/x-api/users/unlike-post.mdx +++ b/x-api/users/unlike-post.mdx @@ -1,3 +1,7 @@ --- openapi: delete /2/users/{id}/likes/{tweet_id} ---- \ No newline at end of file +--- + + +This endpoint requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. + \ No newline at end of file From 7f1baa69a2b9471ce21260b26efbe50ca98e377a Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 21 Apr 2026 16:19:07 -0700 Subject: [PATCH 11/38] Update banner --- overview.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/overview.mdx b/overview.mdx index 949bdeec3..ab425687b 100644 --- a/overview.mdx +++ b/overview.mdx @@ -30,7 +30,7 @@ Earn free [xAI API](https://docs.x.ai) credits when you purchase X API credits ## Get started - +
- The X Activity API is officially out of beta. Subscribe to real-time activity events like profile updates, follows, and more with sub-second delivery via streaming or webhooks. + Owned Reads let you access your own data at reduced cost. Requests for your own posts, bookmarks, followers, likes, and more are priced at $0.001 per resource.

- +
From 1650c45f0b6b92470b67c9283c9df8ddc4d2d206 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Tue, 21 Apr 2026 20:56:01 -0700 Subject: [PATCH 12/38] Add firehose streaming endpoints to recovery and redundancy docs - Add Firehose Streams to intro alongside existing endpoints - Add Firehose, Sample (1%), and Sample10 (Decahose) to backfill table - Add Firehose curl examples for backfill and recovery sections - Document firehose partition-based redundancy (up to 20 connections) - Note that 1% Sample Stream does not support recovery --- .../fundamentals/recovery-and-redundancy.mdx | 27 ++++++++++++++++--- .../fundamentals/recovery-and-redundancy.mdx | 27 ++++++++++++++++--- 2 files changed, 48 insertions(+), 6 deletions(-) diff --git a/enterprise-api/fundamentals/recovery-and-redundancy.mdx b/enterprise-api/fundamentals/recovery-and-redundancy.mdx index 44005386d..a87b25e16 100644 --- a/enterprise-api/fundamentals/recovery-and-redundancy.mdx +++ b/enterprise-api/fundamentals/recovery-and-redundancy.mdx @@ -5,7 +5,7 @@ description: Features for recovering missed data and building resilient streamin keywords: ["recovery", "redundancy", "stream recovery", "reconnect", "fault tolerance", "stream redundancy", "error recovery", "backfill"] --- -Learn how to maximize connection time and recover missed data when using X streaming endpoints including [Filtered Stream](/x-api/posts/filtered-stream/introduction), [Volume Streams](/x-api/posts/volume-streams/introduction), [Powerstream](/x-api/powerstream/introduction), and [Compliance Streams](/x-api/compliance/streams/introduction). +Learn how to maximize connection time and recover missed data when using X streaming endpoints including [Filtered Stream](/x-api/posts/filtered-stream/introduction), [Firehose Streams](/x-api/stream/stream-all-posts), [Volume Streams](/x-api/posts/volume-streams/introduction), [Powerstream](/x-api/powerstream/introduction), and [Compliance Streams](/x-api/compliance/streams/introduction). ## Overview @@ -32,7 +32,7 @@ Benefits: Simply connect to the same stream URL with a second client. Data will be sent through both connections. -Redundant connections are available for Enterprise access. Filtered Stream allows up to two redundant connections for Enterprise projects. Check your specific endpoint documentation for connection limits. +Redundant connections are available for Enterprise access. Filtered Stream allows up to two redundant connections for Enterprise projects. Firehose Streams use a `partition` parameter to support up to 20 concurrent connections, while Sample10 (Decahose) supports up to 2 partitions. Check your specific endpoint documentation for connection limits. --- @@ -48,15 +48,27 @@ Use the **backfill parameter** when reconnecting to receive Posts matched during | Endpoint | Parameter | Example | |:---------|:----------|:--------| | Filtered Stream | `backfill_minutes` | `?backfill_minutes=5` | +| Firehose Stream | `backfill_minutes` | `?backfill_minutes=5` | +| Sample Stream (1%) | `backfill_minutes` | `?backfill_minutes=5` | +| Sample10 Stream (Decahose) | `backfill_minutes` | `?backfill_minutes=5` | | Powerstream | `backfillMinutes` | `?backfillMinutes=5` | -Example request: +Example requests: + +**Filtered Stream:** ```bash curl 'https://api.x.com/2/tweets/search/stream?backfill_minutes=5' \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` +**Firehose Stream:** + +```bash +curl 'https://api.x.com/2/tweets/firehose/stream?backfill_minutes=5&partition=1' \ + -H "Authorization: Bearer $ACCESS_TOKEN" +``` + **Important considerations:** - Older Posts are generally delivered first, before newly matched Posts @@ -93,6 +105,13 @@ curl 'https://api.x.com/2/tweets/search/stream?start_time=2022-07-12T15:10:00Z&e -H "Authorization: Bearer $ACCESS_TOKEN" ``` +**Firehose Stream:** + +```bash +curl 'https://api.x.com/2/tweets/firehose/stream?start_time=2022-07-12T15:10:00Z&end_time=2022-07-12T15:20:00Z&partition=1' \ + -H "Authorization: Bearer $ACCESS_TOKEN" +``` + **Powerstream:** ```bash @@ -105,6 +124,8 @@ curl 'https://api.x.com/2/powerstream?startTime=2022-07-12T15:10:00Z&endTime=202 - Available for Enterprise access - Recovery window: up to 24 hours in the past - Filtered Stream allows 2 concurrent recovery jobs +- Firehose, Sample10 (Decahose), and language-specific firehose streams also support recovery +- The basic 1% Sample Stream does not support recovery; use the Search endpoint instead --- diff --git a/x-api/fundamentals/recovery-and-redundancy.mdx b/x-api/fundamentals/recovery-and-redundancy.mdx index 44005386d..a87b25e16 100644 --- a/x-api/fundamentals/recovery-and-redundancy.mdx +++ b/x-api/fundamentals/recovery-and-redundancy.mdx @@ -5,7 +5,7 @@ description: Features for recovering missed data and building resilient streamin keywords: ["recovery", "redundancy", "stream recovery", "reconnect", "fault tolerance", "stream redundancy", "error recovery", "backfill"] --- -Learn how to maximize connection time and recover missed data when using X streaming endpoints including [Filtered Stream](/x-api/posts/filtered-stream/introduction), [Volume Streams](/x-api/posts/volume-streams/introduction), [Powerstream](/x-api/powerstream/introduction), and [Compliance Streams](/x-api/compliance/streams/introduction). +Learn how to maximize connection time and recover missed data when using X streaming endpoints including [Filtered Stream](/x-api/posts/filtered-stream/introduction), [Firehose Streams](/x-api/stream/stream-all-posts), [Volume Streams](/x-api/posts/volume-streams/introduction), [Powerstream](/x-api/powerstream/introduction), and [Compliance Streams](/x-api/compliance/streams/introduction). ## Overview @@ -32,7 +32,7 @@ Benefits: Simply connect to the same stream URL with a second client. Data will be sent through both connections. -Redundant connections are available for Enterprise access. Filtered Stream allows up to two redundant connections for Enterprise projects. Check your specific endpoint documentation for connection limits. +Redundant connections are available for Enterprise access. Filtered Stream allows up to two redundant connections for Enterprise projects. Firehose Streams use a `partition` parameter to support up to 20 concurrent connections, while Sample10 (Decahose) supports up to 2 partitions. Check your specific endpoint documentation for connection limits. --- @@ -48,15 +48,27 @@ Use the **backfill parameter** when reconnecting to receive Posts matched during | Endpoint | Parameter | Example | |:---------|:----------|:--------| | Filtered Stream | `backfill_minutes` | `?backfill_minutes=5` | +| Firehose Stream | `backfill_minutes` | `?backfill_minutes=5` | +| Sample Stream (1%) | `backfill_minutes` | `?backfill_minutes=5` | +| Sample10 Stream (Decahose) | `backfill_minutes` | `?backfill_minutes=5` | | Powerstream | `backfillMinutes` | `?backfillMinutes=5` | -Example request: +Example requests: + +**Filtered Stream:** ```bash curl 'https://api.x.com/2/tweets/search/stream?backfill_minutes=5' \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` +**Firehose Stream:** + +```bash +curl 'https://api.x.com/2/tweets/firehose/stream?backfill_minutes=5&partition=1' \ + -H "Authorization: Bearer $ACCESS_TOKEN" +``` + **Important considerations:** - Older Posts are generally delivered first, before newly matched Posts @@ -93,6 +105,13 @@ curl 'https://api.x.com/2/tweets/search/stream?start_time=2022-07-12T15:10:00Z&e -H "Authorization: Bearer $ACCESS_TOKEN" ``` +**Firehose Stream:** + +```bash +curl 'https://api.x.com/2/tweets/firehose/stream?start_time=2022-07-12T15:10:00Z&end_time=2022-07-12T15:20:00Z&partition=1' \ + -H "Authorization: Bearer $ACCESS_TOKEN" +``` + **Powerstream:** ```bash @@ -105,6 +124,8 @@ curl 'https://api.x.com/2/powerstream?startTime=2022-07-12T15:10:00Z&endTime=202 - Available for Enterprise access - Recovery window: up to 24 hours in the past - Filtered Stream allows 2 concurrent recovery jobs +- Firehose, Sample10 (Decahose), and language-specific firehose streams also support recovery +- The basic 1% Sample Stream does not support recovery; use the Search endpoint instead --- From 1d2dd5ed23033a7c20592dc23ca893029bd445a4 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Wed, 22 Apr 2026 17:21:35 +0000 Subject: [PATCH 13/38] Update documentation with latest OpenAPI spec --- openapi.json | 4 ++++ x-api/users/follow-user.mdx | 6 +----- x-api/users/like-post.mdx | 6 +----- x-api/users/unfollow-user.mdx | 6 +----- x-api/users/unlike-post.mdx | 6 +----- 5 files changed, 8 insertions(+), 20 deletions(-) diff --git a/openapi.json b/openapi.json index f46e81039..2b74f3c15 100644 --- a/openapi.json +++ b/openapi.json @@ -20493,6 +20493,10 @@ "classification" : { "$ref" : "#/components/schemas/NoteClassification" }, + "is_media_note" : { + "type" : "boolean", + "description" : "Whether the note is a media note." + }, "misleading_tags" : { "type" : "array", "items" : { diff --git a/x-api/users/follow-user.mdx b/x-api/users/follow-user.mdx index 19db16206..449d74830 100644 --- a/x-api/users/follow-user.mdx +++ b/x-api/users/follow-user.mdx @@ -1,7 +1,3 @@ --- openapi: post /2/users/{id}/following ---- - - -This endpoint requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. - \ No newline at end of file +--- \ No newline at end of file diff --git a/x-api/users/like-post.mdx b/x-api/users/like-post.mdx index a6825a2af..e6197dc22 100644 --- a/x-api/users/like-post.mdx +++ b/x-api/users/like-post.mdx @@ -1,7 +1,3 @@ --- openapi: post /2/users/{id}/likes ---- - - -This endpoint requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. - \ No newline at end of file +--- \ No newline at end of file diff --git a/x-api/users/unfollow-user.mdx b/x-api/users/unfollow-user.mdx index f1c1aa5ec..fad80620a 100644 --- a/x-api/users/unfollow-user.mdx +++ b/x-api/users/unfollow-user.mdx @@ -1,7 +1,3 @@ --- openapi: delete /2/users/{source_user_id}/following/{target_user_id} ---- - - -This endpoint requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. - \ No newline at end of file +--- \ No newline at end of file diff --git a/x-api/users/unlike-post.mdx b/x-api/users/unlike-post.mdx index c29de6a20..41a1df715 100644 --- a/x-api/users/unlike-post.mdx +++ b/x-api/users/unlike-post.mdx @@ -1,7 +1,3 @@ --- openapi: delete /2/users/{id}/likes/{tweet_id} ---- - - -This endpoint requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. - \ No newline at end of file +--- \ No newline at end of file From 865eb36a8b9dbbb0a6136f1e5ef420a624d4945d Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Wed, 22 Apr 2026 20:18:23 +0000 Subject: [PATCH 14/38] Update documentation with latest OpenAPI spec --- openapi.json | 110 +++++++++++++-------------------------------------- 1 file changed, 28 insertions(+), 82 deletions(-) diff --git a/openapi.json b/openapi.json index 2b74f3c15..9ead0cfb5 100644 --- a/openapi.json +++ b/openapi.json @@ -2,7 +2,7 @@ "openapi" : "3.0.0", "info" : { "description" : "X API v2 available endpoints", - "version" : "2.161", + "version" : "2.162", "title" : "X API v2", "termsOfService" : "https://developer.x.com/en/developer-terms/agreement-and-policy.html", "contact" : { @@ -15,87 +15,6 @@ } }, "paths" : { - "/2/account_activity/replay/webhooks/{webhook_id}/subscriptions/all" : { - "post" : { - "security" : [ - { - "BearerToken" : [ ] - } - ], - "tags" : [ - "Account Activity" - ], - "summary" : "Create replay job", - "description" : "Creates a replay job to retrieve activities from up to the past 5 days for all subscriptions associated with a given webhook.", - "externalDocs" : { - "url" : "https://docs.x.com/x-api/account-activity/introduction" - }, - "operationId" : "createAccountActivityReplayJob", - "parameters" : [ - { - "name" : "webhook_id", - "in" : "path", - "description" : "The unique identifier for the webhook configuration.", - "required" : true, - "schema" : { - "$ref" : "#/components/schemas/WebhookConfigId" - }, - "style" : "simple" - }, - { - "name" : "from_date", - "in" : "query", - "description" : "The oldest (starting) UTC timestamp (inclusive) from which events will be provided, in `yyyymmddhhmm` format.", - "required" : true, - "schema" : { - "type" : "string", - "pattern" : "^\\d{12}$", - "example" : "202504242000" - }, - "style" : "form" - }, - { - "name" : "to_date", - "in" : "query", - "description" : "The latest (ending) UTC timestamp (exclusive) up to which events will be provided, in `yyyymmddhhmm` format.", - "required" : true, - "schema" : { - "type" : "string", - "pattern" : "^\\d{12}$", - "example" : "202504242200" - }, - "style" : "form" - } - ], - "responses" : { - "200" : { - "description" : "The request has succeeded.", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ReplayJobCreateResponse" - } - } - } - }, - "default" : { - "description" : "The request has failed.", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Error" - } - }, - "application/problem+json" : { - "schema" : { - "$ref" : "#/components/schemas/Problem" - } - } - } - } - } - } - }, "/2/account_activity/subscriptions/count" : { "get" : { "security" : [ @@ -22385,6 +22304,20 @@ "description" : "Language of the Tweet, if detected by X. Returned as a BCP47 language tag.", "example" : "en" }, + "matched_media_notes" : { + "type" : "object", + "description" : "The matched media notes for the post.", + "properties" : { + "match_status" : { + "type" : "string", + "description" : "The status of the media note match.", + "example" : "matched_and_shown" + }, + "note_id" : { + "$ref" : "#/components/schemas/NoteId" + } + } + }, "non_public_metrics" : { "type" : "object", "description" : "Nonpublic engagement metrics for the Tweet at the time of the request.", @@ -22759,6 +22692,10 @@ "media_ids" ], "properties" : { + "description" : { + "type" : "string", + "description" : "Description for the media. Rendered on the Post card for video and Amplify content." + }, "media_ids" : { "type" : "array", "description" : "A list of Media Ids to be attached to a created Tweet.", @@ -22768,6 +22705,9 @@ "$ref" : "#/components/schemas/MediaId" } }, + "preview_media_id" : { + "$ref" : "#/components/schemas/MediaId" + }, "tagged_user_ids" : { "type" : "array", "description" : "A list of User Ids to be tagged in the media for created Tweet.", @@ -22776,6 +22716,10 @@ "items" : { "$ref" : "#/components/schemas/UserId" } + }, + "title" : { + "type" : "string", + "description" : "Title for the media. Rendered on the Post card for video and Amplify content." } }, "additionalProperties" : false @@ -25977,6 +25921,7 @@ "id", "in_reply_to_user_id", "lang", + "matched_media_notes", "media_metadata", "non_public_metrics", "note_tweet", @@ -26011,6 +25956,7 @@ "id", "in_reply_to_user_id", "lang", + "matched_media_notes", "media_metadata", "non_public_metrics", "note_tweet", From 64ae7b8a634956ee6fe81d02dfa014bab7554a01 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Thu, 23 Apr 2026 17:32:10 +0000 Subject: [PATCH 15/38] Update documentation with latest OpenAPI spec --- openapi.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/openapi.json b/openapi.json index 9ead0cfb5..dabd33ea5 100644 --- a/openapi.json +++ b/openapi.json @@ -474,6 +474,14 @@ "security" : [ { "BearerToken" : [ ] + }, + { + "OAuth2UserToken" : [ + "tweet.read" + ] + }, + { + "UserToken" : [ ] } ], "tags" : [ From 1975c70d1b841ec18a46f93d8bed0f4ac453ecaa Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Thu, 23 Apr 2026 19:16:27 -0700 Subject: [PATCH 16/38] Update redirects --- docs.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 9842bd85b..58dbdc398 100644 --- a/docs.json +++ b/docs.json @@ -2728,6 +2728,10 @@ { "source": "/x-api/getting-started/important-resources", "destination": "/important-resources" + }, + { + "source": "/developer-terms/agreement-and-policy", + "destination": "/developer-terms/policy" } ], "seo": { @@ -2766,4 +2770,4 @@ } ] } -} \ No newline at end of file +} From 0cd6d0054858f0707d9422dcac0e96cd1458bfb9 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 27 Apr 2026 17:31:06 +0000 Subject: [PATCH 17/38] Update documentation with latest OpenAPI spec --- openapi.json | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/openapi.json b/openapi.json index dabd33ea5..7b7f3a747 100644 --- a/openapi.json +++ b/openapi.json @@ -22700,10 +22700,68 @@ "media_ids" ], "properties" : { + "call_to_actions" : { + "type" : "object", + "description" : "Call-to-action button rendered on the media entity. Exactly one variant should be set.", + "properties" : { + "app_install" : { + "type" : "object", + "description" : "App Install CTA. At least one store id should be provided.", + "properties" : { + "app_store_id" : { + "type" : "string", + "description" : "Apple App Store iPhone app id." + }, + "ipad_app_store_id" : { + "type" : "string", + "description" : "Apple App Store iPad app id." + }, + "play_store_id" : { + "type" : "string", + "description" : "Google Play Store app id." + } + }, + "additionalProperties" : false + }, + "visit_site" : { + "type" : "object", + "description" : "Visit Site CTA.", + "required" : [ + "url" + ], + "properties" : { + "url" : { + "type" : "string", + "description" : "HTTPS URL the CTA links to." + } + }, + "additionalProperties" : false + }, + "watch_now" : { + "type" : "object", + "description" : "Watch Now CTA.", + "required" : [ + "url" + ], + "properties" : { + "url" : { + "type" : "string", + "description" : "HTTPS URL the CTA links to." + } + }, + "additionalProperties" : false + } + }, + "additionalProperties" : false + }, "description" : { "type" : "string", "description" : "Description for the media. Rendered on the Post card for video and Amplify content." }, + "embeddable" : { + "type" : "boolean", + "description" : "When true, the media's asset URLs do not expire and external syndicated playback is allowed." + }, "media_ids" : { "type" : "array", "description" : "A list of Media Ids to be attached to a created Tweet.", From b7903b9288eef5337ec49f95891aab9bf5aaf620 Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 11:42:55 -0700 Subject: [PATCH 18/38] Update agreement.mdx Signed-off-by: tcaldwell-x --- developer-terms/agreement.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/developer-terms/agreement.mdx b/developer-terms/agreement.mdx index a57429a31..c3036c6f0 100644 --- a/developer-terms/agreement.mdx +++ b/developer-terms/agreement.mdx @@ -3,7 +3,7 @@ title: "X Developer Agreement" keywords: ["developer agreement", "API agreement", "terms of service", "developer terms", "X developer agreement", "API terms", "developer contract"] --- -Last Updated: October 17, 2025 +Last Updated: April 27, 2026 By clicking “Accept & Subscribe”, continuing to pay the recurring subscription fee for Paid Services, or by otherwise accessing or using any Licensed Material, you agree to the terms of our Agreement. Subscriptions auto-renew until canceled, as described below. A verified phone number is required to subscribe. If you've subscribed through another platform, manage your subscription through that platform. @@ -74,6 +74,10 @@ In this Agreement, the following definitions apply: **K. Prohibition on I-Framing:** You shall not, under any circumstances, embed, display, or otherwise incorporate any Licensed Material, X Content, X API, or elements of the X Applications within an iframe, inline frame, or any similar embedding mechanism on your Services or any other platform. This prohibition is absolute and includes, but is not limited to, attempts to frame X Content for display, integration, or redistribution purposes. Violation of this clause may result in immediate termination of your Developer Agreement and your access to the Licensed Material (e.g., X API, X Data License, Developer Console) as outlined in Section VII.I. +**L. Self-Serve Use.** The Free, Basic and Pro plans (as described at developer.x.com/en) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). + +**M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). + **IV. Updates and Removals.** **A. Updates.** X may update, modify or discontinue any features or function of the Licensed Material, in whole or in part, from time to time (in each instance, an “**Update**”). You shall implement and use the most current version of the Licensed Material and make any changes to your Services that are required as a result of the Update, at your sole expense. Updates may adversely affect the way your Services access or communicate with the X API or display X Content. X will not be liable for damages of any sort that result from any Update. @@ -172,4 +176,4 @@ If you are a federal, state, or local government entity in the United States usi **F. Survival.** Sections III (Restrictions on Use), V (Ownership and Feedback), VI (Confidentiality), VII(I) (Termination), VIII (Compliance Audit), IX (Warranty Disclaimer), X (Indemnification), XI (Limitation of Liability), XIII (Dispute Resolution and Class Action Waiver); and XIV (Miscellaneous) of this Agreement will survive the termination of this Agreement. -**G. Entire Agreement.** This Agreement constitutes the entire understanding of the parties regarding the subject matter of this Agreement and supersedes all other agreements between the parties related to the subject matter, whether written or oral. If any provision of this Agreement is held by a court of law to be unenforceable, the remaining provisions of the Agreement will remain in effect. No waiver under this Agreement will be effective unless it is in writing and signed by the party granting the waiver. A waiver granted on one occasion will not operate as a waiver on other occasions. This Agreement does not create or imply any partnership, agency or joint venture. \ No newline at end of file +**G. Entire Agreement.** This Agreement constitutes the entire understanding of the parties regarding the subject matter of this Agreement and supersedes all other agreements between the parties related to the subject matter, whether written or oral. If any provision of this Agreement is held by a court of law to be unenforceable, the remaining provisions of the Agreement will remain in effect. No waiver under this Agreement will be effective unless it is in writing and signed by the party granting the waiver. A waiver granted on one occasion will not operate as a waiver on other occasions. This Agreement does not create or imply any partnership, agency or joint venture. From 46739902b85e99a2b1e6af3784237e3e5c13b5ac Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 11:43:30 -0700 Subject: [PATCH 19/38] Update ppu-agreement.mdx Signed-off-by: tcaldwell-x --- developer-terms/ppu-agreement.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/developer-terms/ppu-agreement.mdx b/developer-terms/ppu-agreement.mdx index 37beabe51..419ee4ffa 100644 --- a/developer-terms/ppu-agreement.mdx +++ b/developer-terms/ppu-agreement.mdx @@ -97,6 +97,10 @@ In this Agreement, the following definitions apply: **K. Prohibition on I-Framing:** You shall not, under any circumstances, embed, display, or otherwise incorporate any Licensed Material, X Content, X API, or elements of the X Applications within an iframe, inline frame, or any similar embedding mechanism on your Services or any other platform. This prohibition is absolute and includes, but is not limited to, attempts to frame X Content for display, integration, or redistribution purposes. Violation of this clause may result in immediate termination of your Developer Agreement and your access to the Licensed Material (e.g., X API, X Data License, Developer Console) as outlined in Section VII.I. +**L. Self-Serve Use.** The Free, Basic and Pro plans (as described at developer.x.com/en) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). + +**M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). + **IV. Updates and Removals.** **A. Updates.** X may update, modify or discontinue any features or function of the Licensed Material, in whole or in part, from time to time (in each instance, an “Update”). You shall implement and use the most current version of the Licensed Material and make any changes to your Services that are required as a result of the Update, at your sole expense. Updates may adversely affect the way your Services access or communicate with the X API or display X Content. X will not be liable for damages of any sort that result from any Update. @@ -217,4 +221,4 @@ If you are a federal, state, or local government entity in the United States usi FOLLOW [**@XDEVELOPERS**](https://x.com/XDevelopers) -[**Subscribe to developer news**](https://developer.x.com/twitterdev-news-subscription) \ No newline at end of file +[**Subscribe to developer news**](https://developer.x.com/twitterdev-news-subscription) From 97d67cb85697630585491e1b85b513a061f6a1d9 Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 11:54:18 -0700 Subject: [PATCH 20/38] Update agreement.mdx Signed-off-by: tcaldwell-x --- developer-terms/agreement.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-terms/agreement.mdx b/developer-terms/agreement.mdx index c3036c6f0..69678c6c2 100644 --- a/developer-terms/agreement.mdx +++ b/developer-terms/agreement.mdx @@ -74,7 +74,7 @@ In this Agreement, the following definitions apply: **K. Prohibition on I-Framing:** You shall not, under any circumstances, embed, display, or otherwise incorporate any Licensed Material, X Content, X API, or elements of the X Applications within an iframe, inline frame, or any similar embedding mechanism on your Services or any other platform. This prohibition is absolute and includes, but is not limited to, attempts to frame X Content for display, integration, or redistribution purposes. Violation of this clause may result in immediate termination of your Developer Agreement and your access to the Licensed Material (e.g., X API, X Data License, Developer Console) as outlined in Section VII.I. -**L. Self-Serve Use.** The Free, Basic and Pro plans (as described at developer.x.com/en) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). +**L. Self-Serve Use.** The Pay-Per-Use, Basic, and Pro plans (as described at developer.x.com/en) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). **M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). From 2aea73e3705108958b815e0d81e4d64d09a69b99 Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 11:54:33 -0700 Subject: [PATCH 21/38] Update ppu-agreement.mdx Signed-off-by: tcaldwell-x --- developer-terms/ppu-agreement.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-terms/ppu-agreement.mdx b/developer-terms/ppu-agreement.mdx index 419ee4ffa..6a60ba710 100644 --- a/developer-terms/ppu-agreement.mdx +++ b/developer-terms/ppu-agreement.mdx @@ -97,7 +97,7 @@ In this Agreement, the following definitions apply: **K. Prohibition on I-Framing:** You shall not, under any circumstances, embed, display, or otherwise incorporate any Licensed Material, X Content, X API, or elements of the X Applications within an iframe, inline frame, or any similar embedding mechanism on your Services or any other platform. This prohibition is absolute and includes, but is not limited to, attempts to frame X Content for display, integration, or redistribution purposes. Violation of this clause may result in immediate termination of your Developer Agreement and your access to the Licensed Material (e.g., X API, X Data License, Developer Console) as outlined in Section VII.I. -**L. Self-Serve Use.** The Free, Basic and Pro plans (as described at developer.x.com/en) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). +**L. Self-Serve Use.** The Pay-Per-Use, Basic, and Pro plans (as described at developer.x.com/en) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). **M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). From 0ad0f2fa941eccd0f3569892fc189af3e3f9b5d7 Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 12:34:09 -0700 Subject: [PATCH 22/38] Update agreement.mdx Signed-off-by: tcaldwell-x --- developer-terms/agreement.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-terms/agreement.mdx b/developer-terms/agreement.mdx index 69678c6c2..1b31fa6b8 100644 --- a/developer-terms/agreement.mdx +++ b/developer-terms/agreement.mdx @@ -74,7 +74,7 @@ In this Agreement, the following definitions apply: **K. Prohibition on I-Framing:** You shall not, under any circumstances, embed, display, or otherwise incorporate any Licensed Material, X Content, X API, or elements of the X Applications within an iframe, inline frame, or any similar embedding mechanism on your Services or any other platform. This prohibition is absolute and includes, but is not limited to, attempts to frame X Content for display, integration, or redistribution purposes. Violation of this clause may result in immediate termination of your Developer Agreement and your access to the Licensed Material (e.g., X API, X Data License, Developer Console) as outlined in Section VII.I. -**L. Self-Serve Use.** The Pay-Per-Use, Basic, and Pro plans (as described at developer.x.com/en) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). +**L. Self-Serve Use.** The Pay-Per-Use, Basic, and Pro plans (as described at [developer.x.com](https://developer.x.com)) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at [developer.x.com](https://developer.x.com)). **M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). From d8f09f592aee2beb4b2513a7c28960bd9424928d Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 12:34:21 -0700 Subject: [PATCH 23/38] Update ppu-agreement.mdx Signed-off-by: tcaldwell-x --- developer-terms/ppu-agreement.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-terms/ppu-agreement.mdx b/developer-terms/ppu-agreement.mdx index 6a60ba710..5530e1b7a 100644 --- a/developer-terms/ppu-agreement.mdx +++ b/developer-terms/ppu-agreement.mdx @@ -97,7 +97,7 @@ In this Agreement, the following definitions apply: **K. Prohibition on I-Framing:** You shall not, under any circumstances, embed, display, or otherwise incorporate any Licensed Material, X Content, X API, or elements of the X Applications within an iframe, inline frame, or any similar embedding mechanism on your Services or any other platform. This prohibition is absolute and includes, but is not limited to, attempts to frame X Content for display, integration, or redistribution purposes. Violation of this clause may result in immediate termination of your Developer Agreement and your access to the Licensed Material (e.g., X API, X Data License, Developer Console) as outlined in Section VII.I. -**L. Self-Serve Use.** The Pay-Per-Use, Basic, and Pro plans (as described at developer.x.com/en) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). +**L. Self-Serve Use.** The Pay-Per-Use, Basic, and Pro plans (as described at [developer.x.com](https://developer.x.com)) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at [developer.x.com](https://developer.x.com)). **M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). From e4b570f9afe15e16d961400f5fd0f68735452019 Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 12:35:54 -0700 Subject: [PATCH 24/38] Update agreement.mdx Signed-off-by: tcaldwell-x --- developer-terms/agreement.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/developer-terms/agreement.mdx b/developer-terms/agreement.mdx index 1b31fa6b8..8b38f5619 100644 --- a/developer-terms/agreement.mdx +++ b/developer-terms/agreement.mdx @@ -70,13 +70,13 @@ In this Agreement, the following definitions apply: **I. Tokens.** X may limit the number of tokens that it provides to you, including but not limited to tokens that enable access and use of functionality or features on X Applications. -**J. Access Tiers.** X provides different tiers of access (as described at [developer.x.com/en](http://developer.x.com/en)) to the Licensed Material, and you shall subscribe to the tier that best fits your use case. X may, at any time, review your use of its Licensed Materials and require a change in the access tier to which you are subscribed, including but not limited to, application for Enterprise access (as described at [developer.x.com/en](http://developer.x.com/en)). +**J. Access Tiers.** X provides different tiers of access (as described at [developer.x.com](http://developer.x.com)) to the Licensed Material, and you shall subscribe to the tier that best fits your use case. X may, at any time, review your use of its Licensed Materials and require a change in the access tier to which you are subscribed, including but not limited to, application for Enterprise access (as described at [developer.x.com](http://developer.x.com)). **K. Prohibition on I-Framing:** You shall not, under any circumstances, embed, display, or otherwise incorporate any Licensed Material, X Content, X API, or elements of the X Applications within an iframe, inline frame, or any similar embedding mechanism on your Services or any other platform. This prohibition is absolute and includes, but is not limited to, attempts to frame X Content for display, integration, or redistribution purposes. Violation of this clause may result in immediate termination of your Developer Agreement and your access to the Licensed Material (e.g., X API, X Data License, Developer Console) as outlined in Section VII.I. **L. Self-Serve Use.** The Pay-Per-Use, Basic, and Pro plans (as described at [developer.x.com](https://developer.x.com)) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at [developer.x.com](https://developer.x.com)). -**M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). +**M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com). **IV. Updates and Removals.** @@ -168,7 +168,7 @@ If you are a federal, state, or local government entity in the United States usi **B. User Protection.** Unless explicitly approved by X in writing, you shall not use, or knowingly display, distribute, or otherwise make X Content, or information derived from X Content, available for purpose of: (a) conducting or providing surveillance or gathering intelligence, including but not limited to investigating or tracking X users or X Content; (b) conducting or providing analysis or research for any unlawful or discriminatory purpose or in a manner that would be inconsistent with X users' reasonable expectations of privacy; (c) monitoring sensitive events (including but not limited to protests, rallies, or community organizing meetings); or (d) targeting, segmenting, or profiling individuals based on sensitive personal information, including their health (e.g., pregnancy), negative financial status or condition, political affiliation or beliefs, racial or ethnic origin, religious or philosophical affiliation or beliefs, sex life or sexual orientation, trade union membership, X Content relating to any alleged or actual commission of a crime, or any other sensitive categories of personal information prohibited by law. -**C. Government Use.** If you display, distribute, or otherwise make available any X Content to Users that are, or that act on behalf of, any government-related entity (each a “**Government End User**”); (a) you must apply for (or already subscribe to) an Enterprise plan (as described at [developer.x.com/en](https://developer.x.com/en)); (b) you shall identify all such Government End Users when submitting your use case for review to X; and (c) you shall thereafter notify X in writing of any new Government End Users or any new use cases with existing Government End Users before the Services display, distribute, or otherwise make available any X Content to a Government End User or for any new use case. X may prohibit you from making X Content available to any Government End User. You shall not use, or knowingly display, distribute, or otherwise make X Content, or information derived from X Content, available to any Government End User whose primary function or mission includes conducting surveillance or gathering intelligence. If law enforcement requests information about X or its users for purposes of an ongoing investigation, you may refer them to X’s Guidelines for Law Enforcement located at [**https://help.x.com/rules-and-policies/x-law-enforcement-support**](https://help.x.com/rules-and-policies/x-law-enforcement-support). The X API and X Content are "commercial items" as that term is defined at 48 C.F.R. 2.101, consisting of "commercial computer software" and "commercial computer software documentation" as such terms are used in 48 C.F.R. 12.212. Any use, modification, derivative, reproduction, release, performance, display, disclosure, or distribution of the X API or X Content by any government entity is prohibited except as expressly permitted by the terms of this Agreement. Additionally, any use by U.S. government entities must be in accordance with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4. If you use the X API or X Content in your official capacity as an employee or representative of a U.S. state or local government entity and you are legally unable to accept the indemnity, jurisdiction, venue, or other clauses herein, then those clauses do not apply to such entity to the extent required by law. Contractor/manufacturer is X Corp., 865 FM 1209, Building 2, Bastrop, TX 78602, USA. +**C. Government Use.** If you display, distribute, or otherwise make available any X Content to Users that are, or that act on behalf of, any government-related entity (each a “**Government End User**”); (a) you must apply for (or already subscribe to) an Enterprise plan (as described at [developer.x.com](https://developer.x.com)); (b) you shall identify all such Government End Users when submitting your use case for review to X; and (c) you shall thereafter notify X in writing of any new Government End Users or any new use cases with existing Government End Users before the Services display, distribute, or otherwise make available any X Content to a Government End User or for any new use case. X may prohibit you from making X Content available to any Government End User. You shall not use, or knowingly display, distribute, or otherwise make X Content, or information derived from X Content, available to any Government End User whose primary function or mission includes conducting surveillance or gathering intelligence. If law enforcement requests information about X or its users for purposes of an ongoing investigation, you may refer them to X’s Guidelines for Law Enforcement located at [**https://help.x.com/rules-and-policies/x-law-enforcement-support**](https://help.x.com/rules-and-policies/x-law-enforcement-support). The X API and X Content are "commercial items" as that term is defined at 48 C.F.R. 2.101, consisting of "commercial computer software" and "commercial computer software documentation" as such terms are used in 48 C.F.R. 12.212. Any use, modification, derivative, reproduction, release, performance, display, disclosure, or distribution of the X API or X Content by any government entity is prohibited except as expressly permitted by the terms of this Agreement. Additionally, any use by U.S. government entities must be in accordance with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4. If you use the X API or X Content in your official capacity as an employee or representative of a U.S. state or local government entity and you are legally unable to accept the indemnity, jurisdiction, venue, or other clauses herein, then those clauses do not apply to such entity to the extent required by law. Contractor/manufacturer is X Corp., 865 FM 1209, Building 2, Bastrop, TX 78602, USA. **D. Compliance with Laws; Export and Import.** Each party will comply with all applicable foreign, federal, state, and local laws, rules and regulations, including without limitation all laws relating to bribery and/or corruption. The Licensed Material is subject to U.S. export laws and may be subject to import and use laws of the country where it is delivered or used. You shall abide by these laws. Under these laws, the Licensed Material may not be sold, leased, downloaded, moved, exported, re-exported, or transferred across borders without a license, or approval from the relevant government authority, to any country or to any foreign national restricted by these laws, including countries embargoed by the U.S. Government (currently Cuba, Iran, North Korea, Northern Sudan and Syria), to any restricted or denied end-user, including but not limited to any person or entity prohibited by the U.S. Office of Foreign Assets Control, or for any restricted end-use. You shall maintain all rights and licenses that are required for your Services. From 3e346edb15bc4431a2f8d56ed5b8a9624c066c8a Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 12:36:14 -0700 Subject: [PATCH 25/38] Update ppu-agreement.mdx Signed-off-by: tcaldwell-x --- developer-terms/ppu-agreement.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-terms/ppu-agreement.mdx b/developer-terms/ppu-agreement.mdx index 5530e1b7a..cc0001e40 100644 --- a/developer-terms/ppu-agreement.mdx +++ b/developer-terms/ppu-agreement.mdx @@ -99,7 +99,7 @@ In this Agreement, the following definitions apply: **L. Self-Serve Use.** The Pay-Per-Use, Basic, and Pro plans (as described at [developer.x.com](https://developer.x.com)) are designed for hobbyists, commercial prototyping, initial development, early-stage X product integrations, and supporting applications with a limited number of end-users. If you use the X API beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at [developer.x.com](https://developer.x.com)). -**M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com/en). +**M. Commercial Use:** If you use the X API beyond the scope of hobbyist projects, commercial prototyping, initial development, early-stage X product integrations, or for applications with a limited number of end-users, then you must apply (or already subscribe to) an Enterprise plan (as described at developer.x.com). **IV. Updates and Removals.** From 29677de48a7fbff5161be61fd94a39fd2fd16969 Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 12:37:34 -0700 Subject: [PATCH 26/38] Update policy.mdx Signed-off-by: tcaldwell-x --- developer-terms/policy.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer-terms/policy.mdx b/developer-terms/policy.mdx index 60676c91f..ef9c2eadf 100644 --- a/developer-terms/policy.mdx +++ b/developer-terms/policy.mdx @@ -140,7 +140,7 @@ You agree that X may, from time to time, review your _Sign in with X_ option and You can avoid many potential pitfalls while using the X API by ensuring that your service has been built the right way from day 1. This section of the Developer Policy contains rules that all developers must follow before using the X API or X Content. -The Free, Basic, and Pro plans (as described at [developer.x.com/en](http://developer.x.com/en)) are designed for hobbyists, commercial prototyping, early-stage X product integrations, and supporting applications with limited end-users. If you use the X API and X Content beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at [developer.x.com/en](http://developer.x.com/en)). +The Free, Basic, and Pro plans (as described at [developer.x.com](http://developer.x.com)) are designed for hobbyists, commercial prototyping, early-stage X product integrations, and supporting applications with limited end-users. If you use the X API and X Content beyond this scope, then you must apply (or already subscribe to) an Enterprise plan (as described at [developer.x.com](http://developer.x.com)). **We review all proposed uses of the X developer platform to verify policy compliance — so you’re required to disclose (and update, as applicable) your planned use of the X API and X Content in order to be granted and to maintain access.** All new developers must [apply for a developer account](https://developer.x.com/portal/petition/essential/basic-info) to access the X API. Current developers without an approved developer account must apply for one as directed to do so by X. As part of this process, you’ll need to provide us with a written description of your intended uses of the X API and X Content. @@ -249,4 +249,4 @@ If your application allows people to post with their location you must comply wi ## X passwords -**You may not store X passwords, or request that people provide their X password, account credentials, or developer application information (including consumer key) to you directly.** We suggest the use of [Sign-in with X](/fundamentals/authentication/guides/log-in-with-x) as the authentication tool to link your service and people on X. \ No newline at end of file +**You may not store X passwords, or request that people provide their X password, account credentials, or developer application information (including consumer key) to you directly.** We suggest the use of [Sign-in with X](/fundamentals/authentication/guides/log-in-with-x) as the authentication tool to link your service and people on X. From 195b38134b59f42d7664cef37ed7f99f3ba1d303 Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 12:38:59 -0700 Subject: [PATCH 27/38] Update restricted-use-cases.mdx Signed-off-by: tcaldwell-x --- developer-terms/restricted-use-cases.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/developer-terms/restricted-use-cases.mdx b/developer-terms/restricted-use-cases.mdx index 1ce0d8086..169efb501 100644 --- a/developer-terms/restricted-use-cases.mdx +++ b/developer-terms/restricted-use-cases.mdx @@ -3,18 +3,18 @@ title: "More about restricted uses of the X APIs" keywords: ["restricted use cases", "API restrictions", "prohibited uses", "sensitive information", "API limitations", "restricted usage", "forbidden uses"] --- -Use of our developer platform requires that you review and agree to our [Developer Agreement and Policy](/developer-terms/agreement), as well as our related policies, including the [Display Requirements](https://developer.x.com/en/developer-terms/display-requirements.html) and [Automation Rules](https://help.twitter.com/en/rules-and-policies/twitter-automation). Among other things, our agreements and policies provide guidance about several restricted use cases. We’ve provided additional information about some of these restrictions below. +Use of our developer platform requires that you review and agree to our [Developer Agreement and Policy](/developer-terms/agreement), as well as our related policies, including the [Display Requirements](https://docs.x.com/developer-terms/display-requirements) and [Automation Rules](https://help.x.com/en/rules-and-policies/twitter-automation). Among other things, our agreements and policies provide guidance about several restricted use cases. We’ve provided additional information about some of these restrictions below. ## Automation, spam, and auto-responses The use of X's APIs and developer products to create spam, or engage in spammy behavior, is prohibited. You should review the [X Rules](https://t.co/rules) on spam, and ensure that your application does not, and does not enable users to, violate our policies. -If your application will be used to perform write actions on the X service, including posting Posts, following accounts, or sending Direct Messages, you should carefully review the [Automation Rules](https://support.twitter.com/articles/76915) to ensure your service complies with our guidelines. In particular, you should: +If your application will be used to perform write actions on the X service, including posting Posts, following accounts, or sending Direct Messages, you should carefully review the [Automation Rules](https://support.x.com/articles/76915) to ensure your service complies with our guidelines. In particular, you should: - Always get a user’s explicit consent before sending them [automated replies or messages](https://twittercommunity.com/t/policy-clarification-automated-replies-and-mentions/94444) - Immediately respect user requests to opt-out of being contacted by you - Never perform bulk, aggressive, or spammy actions, including [bulk following](https://twittercommunity.com/t/policy-clarification-aggressive-following-and-inorganic-following-behavior/92769) -- Never post identical or substantially similar content across [multiple accounts](https://blog.twitter.com/developer/en_us/topics/tips/2018/automation-and-the-use-of-multiple-accounts.html) +- Never post identical or substantially similar content across [multiple accounts](https://blog.x.com/developer/en_us/topics/tips/2018/automation-and-the-use-of-multiple-accounts.html) ## Sensitive information @@ -59,7 +59,7 @@ There are a few other points to keep in mind about redistributing X content: - Individuals redistributing Post IDs and/or User IDs on behalf of an academic institution for the sole purpose of non-commercial research are permitted to redistribute an unlimited number of Post IDs and/or User IDs. - To request permission to share X content as outlined above, please use the API Policy support form. -To the extent you are permitted to distribute X content to a third party, note that this content remains subject to the Developer Agreement and Policy, and those third parties must agree to the X [Terms of Service](https://twitter.com/en/tos), [Privacy Policy](https://twitter.com/en/privacy), [Developer Agreement](/developer-terms/agreement), and [Developer Policy](/developer-terms/policy) before receiving X content. +To the extent you are permitted to distribute X content to a third party, note that this content remains subject to the Developer Agreement and Policy, and those third parties must agree to the X [Terms of Service](https://x.com/en/tos), [Privacy Policy](https://x.com/en/privacy), [Developer Agreement](/developer-terms/agreement), and [Developer Policy](/developer-terms/policy) before receiving X content. ## Multiple applications @@ -75,7 +75,7 @@ Do not use the X APIs to measure the availability, performance, functionality, o - Calculate aggregate X user metrics, such as the total number of active users or accounts - Calculate aggregate X Post metrics, such as the total number of Posts per day, or the number of user engagements or account engagements -- Measure or analyze spam or security on X, except as permitted in the [X Rules](https://help.twitter.com/en/rules-and-policies/twitter-rules) +- Measure or analyze spam or security on X, except as permitted in the [X Rules](https://help.x.com/en/rules-and-policies/twitter-rules) ## Surveillance, privacy, and user protection @@ -95,4 +95,4 @@ These policies apply to all users of our APIs. Any misuse of the X APIs for thes For additional information for law enforcement authorities seeking information about X accounts, visit https://t.co/le. -In addition, at this time, X prohibits any use of the X APIs and/or X Content to fine-tune or train a foundation or frontier model with the exception of [Grok](https://help.x.com/en/using-x/about-grok). \ No newline at end of file +In addition, at this time, X prohibits any use of the X APIs and/or X Content to fine-tune or train a foundation or frontier model with the exception of [Grok](https://help.x.com/en/using-x/about-grok). From f9113aa8dbe093bf782502edeb5df675a6c17c70 Mon Sep 17 00:00:00 2001 From: tcaldwell-x Date: Mon, 27 Apr 2026 12:41:07 -0700 Subject: [PATCH 28/38] Update ads-api-agreement.mdx Signed-off-by: tcaldwell-x --- developer-terms/ads-api-agreement.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer-terms/ads-api-agreement.mdx b/developer-terms/ads-api-agreement.mdx index 051261849..aae4873cb 100644 --- a/developer-terms/ads-api-agreement.mdx +++ b/developer-terms/ads-api-agreement.mdx @@ -309,7 +309,7 @@ These Analytics Data Display Requirements govern how Company can display Data wi ### Defined Metrics -All campaigns shown in the Company Service that display Data must include the specific X-defined metrics associated with various campaign objectives (each, a “**Campaign Objective**”), which metrics must be calculated by Company based on the endpoints and formulas located at: [https://developer.x.com/en/docs/x-ads-api/analytics/overview/metrics-by-objective](https://developer.x.com/en/docs/x-ads-api/analytics/overview/metrics-by-objective) (or any other successor URL that X may elect from time to time). +All campaigns shown in the Company Service that display Data must include the specific X-defined metrics associated with various campaign objectives (each, a “**Campaign Objective**”), which metrics must be calculated by Company based on the endpoints and formulas located at: [https://docs.x.com/x-ads-api/analytics#metrics-by-objective](https://docs.x.com/x-ads-api/analytics#metrics-by-objective) (or any other successor URL that X may elect from time to time). ### Display Guidelines @@ -415,4 +415,4 @@ X may immediately terminate or suspend these TMP Partner Terms, any rights grant ### 8. Modifications. -X reserves the rights, exercisable at its sole discretion, to modify the terms and conditions of these TMP Partner Terms and/or the Badges at any time and to take appropriate action against any unauthorized or non-conforming use of the Badges. If Company has any questions about usage of the Badges, please contact [trademarks@x.com](mailto:trademarks@x.com) for assistance, or write to us at: X Corp., Attention: Legal Department, 865 FM 1209, Building 2, Bastrop, TX 78602, USA. \ No newline at end of file +X reserves the rights, exercisable at its sole discretion, to modify the terms and conditions of these TMP Partner Terms and/or the Badges at any time and to take appropriate action against any unauthorized or non-conforming use of the Badges. If Company has any questions about usage of the Badges, please contact [trademarks@x.com](mailto:trademarks@x.com) for assistance, or write to us at: X Corp., Attention: Legal Department, 865 FM 1209, Building 2, Bastrop, TX 78602, USA. From 9b4f947346f06651cf775ca261ea1d2c29a6b60b Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Mon, 4 May 2026 18:56:39 -0700 Subject: [PATCH 29/38] Update theme --- docs.json | 3042 +++++++++++++++-------------------------------------- style.css | 20 +- 2 files changed, 889 insertions(+), 2173 deletions(-) diff --git a/docs.json b/docs.json index 58dbdc398..c0b085200 100644 --- a/docs.json +++ b/docs.json @@ -1,6 +1,6 @@ { "$schema": "https://mintlify.com/docs.json", - "theme": "mint", + "theme": "luma", "name": "X", "colors": { "primary": "#0E0E0E", @@ -9,12 +9,12 @@ }, "favicon": "/favicon.png", "navigation": { - "versions": [ + "products": [ { - "version": "English", + "product": "X API", "tabs": [ { - "tab": "Home", + "tab": "Documentation", "groups": [ { "group": "Getting Started", @@ -74,19 +74,6 @@ ] } ] - }, - { - "group": "X Ads API", - "pages": [ - "x-ads-api/introduction", - { - "group": "Getting started", - "pages": [ - "x-ads-api/getting-started/step-by-step-guide", - "x-ads-api/getting-started/increasing-access" - ] - } - ] } ] }, @@ -147,6 +134,7 @@ "pages": [ "enterprise/partner-directory", "enterprise/customer-directory", + "success-stories", { "group": "Request Access", "pages": [ @@ -169,744 +157,751 @@ ] }, { - "tab": "X API", - "groups": [ + "tab": "API Reference", + "dropdowns": [ { - "group": "Overview", - "pages": [ - "x-api/overview", + "dropdown": "General", + "icon": "code", + "groups": [ { - "group": "Fundamentals", + "group": "Overview", "pages": [ - "x-api/fundamentals/data-dictionary", - "x-api/fundamentals/fields", - "x-api/fundamentals/expansions", - "x-api/fundamentals/post-annotations", - "x-api/fundamentals/metrics", - "x-api/fundamentals/conversation-id", - "x-api/fundamentals/pagination", - "x-api/fundamentals/versioning", - "x-api/fundamentals/consistency", - "x-api/fundamentals/rate-limits", - "x-api/fundamentals/post-cap", - "x-api/fundamentals/edit-posts", - "x-api/fundamentals/response-codes-and-errors", - { - "group": "Streaming", - "pages": [ - "x-api/fundamentals/consuming-streaming-data", - "x-api/fundamentals/handling-disconnections", - "x-api/fundamentals/high-volume-capacity", - "x-api/fundamentals/recovery-and-redundancy" + "x-api/overview", + { + "group": "Fundamentals", + "pages": [ + "x-api/fundamentals/data-dictionary", + "x-api/fundamentals/fields", + "x-api/fundamentals/expansions", + "x-api/fundamentals/post-annotations", + "x-api/fundamentals/metrics", + "x-api/fundamentals/conversation-id", + "x-api/fundamentals/pagination", + "x-api/fundamentals/versioning", + "x-api/fundamentals/consistency", + "x-api/fundamentals/rate-limits", + "x-api/fundamentals/post-cap", + "x-api/fundamentals/edit-posts", + "x-api/fundamentals/response-codes-and-errors", + { + "group": "Streaming", + "pages": [ + "x-api/fundamentals/consuming-streaming-data", + "x-api/fundamentals/handling-disconnections", + "x-api/fundamentals/high-volume-capacity", + "x-api/fundamentals/recovery-and-redundancy" + ] + } ] } ] - } - ] - }, - { - "group": "Posts", - "pages": [ + }, { - "group": "Search", + "group": "Posts", "pages": [ - "x-api/posts/search/introduction", { - "group": "Guides", + "group": "Search", "pages": [ + "x-api/posts/search/introduction", { - "group": "Quickstart", + "group": "Guides", "pages": [ - "x-api/posts/search/quickstart/recent-search", - "x-api/posts/search/quickstart/full-archive-search" + { + "group": "Quickstart", + "pages": [ + "x-api/posts/search/quickstart/recent-search", + "x-api/posts/search/quickstart/full-archive-search" + ] + }, + { + "group": "Integration guide", + "pages": [ + "x-api/posts/search/integrate/overview", + "x-api/posts/search/integrate/build-a-query", + "x-api/posts/search/integrate/operators", + "x-api/posts/search/integrate/paginate" + ] + } ] }, + "x-api/posts/search-all-posts", + "x-api/posts/search-recent-posts" + ] + }, + { + "group": "Post Counts", + "pages": [ + "x-api/posts/counts/introduction", { - "group": "Integration guide", + "group": "Guides", "pages": [ - "x-api/posts/search/integrate/overview", - "x-api/posts/search/integrate/build-a-query", - "x-api/posts/search/integrate/operators", - "x-api/posts/search/integrate/paginate" + { + "group": "Quickstart", + "pages": [ + "x-api/posts/counts/quickstart/recent-tweet-counts", + "x-api/posts/counts/quickstart/full-archive-tweet-counts" + ] + }, + { + "group": "Integration guide", + "pages": [ + "x-api/posts/counts/integrate/overview", + "x-api/posts/counts/integrate/build-a-query" + ] + } ] - } + }, + "x-api/posts/get-count-of-all-posts", + "x-api/posts/get-count-of-recent-posts" ] }, - "x-api/posts/search-all-posts", - "x-api/posts/search-recent-posts" - ] - }, - { - "group": "Post Counts", - "pages": [ - "x-api/posts/counts/introduction", { - "group": "Guides", + "group": "Filtered Stream", "pages": [ + "x-api/posts/filtered-stream/introduction", { - "group": "Quickstart", + "group": "Guides", "pages": [ - "x-api/posts/counts/quickstart/recent-tweet-counts", - "x-api/posts/counts/quickstart/full-archive-tweet-counts" + "x-api/posts/filtered-stream/quickstart", + { + "group": "Integration guide", + "pages": [ + "x-api/posts/filtered-stream/integrate/build-a-rule", + "x-api/posts/filtered-stream/integrate/operators", + "x-api/posts/filtered-stream/integrate/matching-returned-tweets", + "x-api/fundamentals/consuming-streaming-data", + "x-api/fundamentals/handling-disconnections", + "x-api/fundamentals/high-volume-capacity", + "x-api/fundamentals/recovery-and-redundancy" + ] + } ] }, + "x-api/stream/stream-filtered-posts", + "x-api/stream/get-stream-rules", + "x-api/stream/get-stream-rule-counts", + "x-api/stream/update-stream-rules" + ] + }, + { + "group": "Timelines", + "pages": [ + "x-api/posts/timelines/introduction", { - "group": "Integration guide", + "group": "Guides", "pages": [ - "x-api/posts/counts/integrate/overview", - "x-api/posts/counts/integrate/build-a-query" + { + "group": "Quickstart", + "pages": [ + "x-api/posts/timelines/quickstart/reverse-chron-quickstart", + "x-api/posts/timelines/quickstart/user-mention-quickstart" + ] + }, + "x-api/posts/timelines/integrate" ] - } + }, + "x-api/users/get-posts", + "x-api/users/get-mentions", + "x-api/users/get-timeline" ] }, - "x-api/posts/get-count-of-all-posts", - "x-api/posts/get-count-of-recent-posts" - ] - }, - { - "group": "Filtered Stream", - "pages": [ - "x-api/posts/filtered-stream/introduction", { - "group": "Guides", + "group": "Post Lookup", "pages": [ - "x-api/posts/filtered-stream/quickstart", + "x-api/posts/lookup/introduction", { - "group": "Integration guide", + "group": "Guides", "pages": [ - "x-api/posts/filtered-stream/integrate/build-a-rule", - "x-api/posts/filtered-stream/integrate/operators", - "x-api/posts/filtered-stream/integrate/matching-returned-tweets", - "x-api/fundamentals/consuming-streaming-data", - "x-api/fundamentals/handling-disconnections", - "x-api/fundamentals/high-volume-capacity", - "x-api/fundamentals/recovery-and-redundancy" + "x-api/posts/lookup/quickstart", + "x-api/posts/lookup/integrate" ] - } + }, + "x-api/posts/get-posts-by-ids", + "x-api/posts/get-post-by-id" ] }, - "x-api/stream/stream-filtered-posts", - "x-api/stream/get-stream-rules", - "x-api/stream/get-stream-rule-counts", - "x-api/stream/update-stream-rules" - ] - }, - { - "group": "Timelines", - "pages": [ - "x-api/posts/timelines/introduction", { - "group": "Guides", + "group": "Bookmarks", "pages": [ + "x-api/posts/bookmarks/introduction", { - "group": "Quickstart", + "group": "Guides", "pages": [ - "x-api/posts/timelines/quickstart/reverse-chron-quickstart", - "x-api/posts/timelines/quickstart/user-mention-quickstart" + { + "group": "Quickstart", + "pages": [ + "x-api/posts/bookmarks/quickstart/bookmarks-lookup", + "x-api/posts/bookmarks/quickstart/manage-bookmarks" + ] + }, + "x-api/posts/bookmarks/integrate" ] }, - "x-api/posts/timelines/integrate" + { + "group": "Bookmark Folders", + "pages": [ + "x-api/users/get-bookmark-folders", + "x-api/bookmarks/get-bookmarks-by-folder-id" + ] + }, + "x-api/users/get-bookmarks", + "x-api/users/create-bookmark", + "x-api/users/delete-bookmark" ] }, - "x-api/users/get-posts", - "x-api/users/get-mentions", - "x-api/users/get-timeline" - ] - }, - { - "group": "Post Lookup", - "pages": [ - "x-api/posts/lookup/introduction", { - "group": "Guides", + "group": "Manage Posts", "pages": [ - "x-api/posts/lookup/quickstart", - "x-api/posts/lookup/integrate" + "x-api/posts/manage-tweets/introduction", + { + "group": "Guides", + "pages": [ + "x-api/posts/manage-tweets/quickstart", + "x-api/posts/manage-tweets/integrate" + ] + }, + "x-api/posts/create-post", + "x-api/posts/delete-post" ] }, - "x-api/posts/get-posts-by-ids", - "x-api/posts/get-post-by-id" - ] - }, - { - "group": "Bookmarks", - "pages": [ - "x-api/posts/bookmarks/introduction", { - "group": "Guides", + "group": "Reposts", "pages": [ + "x-api/posts/retweets/introduction", { - "group": "Quickstart", + "group": "Guides", "pages": [ - "x-api/posts/bookmarks/quickstart/bookmarks-lookup", - "x-api/posts/bookmarks/quickstart/manage-bookmarks" + { + "group": "Quickstart", + "pages": [ + "x-api/posts/retweets/quickstart/retweets-lookup", + "x-api/posts/retweets/quickstart/manage-retweets", + "x-api/posts/retweets/quickstart/retweets-of-me" + ] + }, + "x-api/posts/retweets/integrate" ] }, - "x-api/posts/bookmarks/integrate" + "x-api/posts/get-reposted-by", + "x-api/users/repost-post", + "x-api/users/unrepost-post", + "x-api/posts/get-reposts", + "x-api/users/get-reposts-of-me" ] }, { - "group": "Bookmark Folders", + "group": "Quotes", "pages": [ - "x-api/users/get-bookmark-folders", - "x-api/bookmarks/get-bookmarks-by-folder-id" + "x-api/posts/quote-tweets/introduction", + { + "group": "Guides", + "pages": [ + "x-api/posts/quote-tweets/quickstart" + ] + }, + "x-api/posts/get-quoted-posts" ] }, - "x-api/users/get-bookmarks", - "x-api/users/create-bookmark", - "x-api/users/delete-bookmark" - ] - }, - { - "group": "Manage Posts", - "pages": [ - "x-api/posts/manage-tweets/introduction", { - "group": "Guides", + "group": "Hide replies", "pages": [ - "x-api/posts/manage-tweets/quickstart", - "x-api/posts/manage-tweets/integrate" + "x-api/posts/hide-replies/introduction", + "x-api/posts/hide-replies/apps", + { + "group": "Guides", + "pages": [ + "x-api/posts/hide-replies/quickstart", + { + "group": "Integration guide", + "pages": [ + "x-api/posts/hide-replies/integrate/manage-replies-by-topic", + "x-api/posts/hide-replies/integrate/manage-replies-in-realtime" + ] + } + ] + }, + "x-api/posts/hide-reply" ] - }, - "x-api/posts/create-post", - "x-api/posts/delete-post" + } ] }, { - "group": "Reposts", + "group": "Users", "pages": [ - "x-api/posts/retweets/introduction", { - "group": "Guides", + "group": "User Lookup", "pages": [ + "x-api/users/lookup/introduction", { - "group": "Quickstart", + "group": "Guides", "pages": [ - "x-api/posts/retweets/quickstart/retweets-lookup", - "x-api/posts/retweets/quickstart/manage-retweets", - "x-api/posts/retweets/quickstart/retweets-of-me" + { + "group": "Quickstart", + "pages": [ + "x-api/users/lookup/quickstart/user-lookup", + "x-api/users/lookup/quickstart/authenticated-lookup" + ] + }, + "x-api/users/lookup/integrate" ] }, - "x-api/posts/retweets/integrate" + "x-api/users/get-user-by-id", + "x-api/users/get-users-by-ids", + "x-api/users/get-users-by-usernames", + "x-api/users/get-user-by-username", + "x-api/users/get-my-user" ] }, - "x-api/posts/get-reposted-by", - "x-api/users/repost-post", - "x-api/users/unrepost-post", - "x-api/posts/get-reposts", - "x-api/users/get-reposts-of-me" - ] - }, - { - "group": "Quotes", - "pages": [ - "x-api/posts/quote-tweets/introduction", { - "group": "Guides", + "group": "Search", "pages": [ - "x-api/posts/quote-tweets/quickstart" + "x-api/users/search/introduction", + "x-api/users/search-users" ] }, - "x-api/posts/get-quoted-posts" - ] - }, - { - "group": "Hide replies", - "pages": [ - "x-api/posts/hide-replies/introduction", - "x-api/posts/hide-replies/apps", { - "group": "Guides", + "group": "Follows", "pages": [ - "x-api/posts/hide-replies/quickstart", + "x-api/users/follows/introduction", { - "group": "Integration guide", + "group": "Guides", "pages": [ - "x-api/posts/hide-replies/integrate/manage-replies-by-topic", - "x-api/posts/hide-replies/integrate/manage-replies-in-realtime" + "x-api/users/follows/quickstart" ] - } + }, + "x-api/users/get-followers", + "x-api/users/get-following", + "x-api/users/follow-user", + "x-api/users/unfollow-user" ] }, - "x-api/posts/hide-reply" - ] - } - ] - }, - { - "group": "Users", - "pages": [ - { - "group": "User Lookup", - "pages": [ - "x-api/users/lookup/introduction", { - "group": "Guides", + "group": "Mutes", "pages": [ + "x-api/users/mutes/introduction", { - "group": "Quickstart", + "group": "Guides", "pages": [ - "x-api/users/lookup/quickstart/user-lookup", - "x-api/users/lookup/quickstart/authenticated-lookup" + { + "group": "Quickstart", + "pages": [ + "x-api/users/mutes/quickstart/manage-mutes-quickstart", + "x-api/users/mutes/quickstart/mutes-lookup" + ] + }, + "x-api/users/mutes/integrate" ] }, - "x-api/users/lookup/integrate" - ] - }, - "x-api/users/get-user-by-id", - "x-api/users/get-users-by-ids", - "x-api/users/get-users-by-usernames", - "x-api/users/get-user-by-username", - "x-api/users/get-my-user" - ] - }, - { - "group": "Search", - "pages": [ - "x-api/users/search/introduction", - "x-api/users/search-users" - ] - }, - { - "group": "Follows", - "pages": [ - "x-api/users/follows/introduction", - { - "group": "Guides", - "pages": [ - "x-api/users/follows/quickstart" + "x-api/users/mute-user", + "x-api/users/unmute-user", + "x-api/users/get-muting" ] }, - "x-api/users/get-followers", - "x-api/users/get-following", - "x-api/users/follow-user", - "x-api/users/unfollow-user" - ] - }, - { - "group": "Mutes", - "pages": [ - "x-api/users/mutes/introduction", { - "group": "Guides", + "group": "Blocks", "pages": [ + "x-api/users/blocks/introduction", { - "group": "Quickstart", + "group": "Guides", "pages": [ - "x-api/users/mutes/quickstart/manage-mutes-quickstart", - "x-api/users/mutes/quickstart/mutes-lookup" + "x-api/users/blocks/quickstart", + "x-api/users/blocks/integrate" ] }, - "x-api/users/mutes/integrate" + "x-api/users/get-blocking" ] }, - "x-api/users/mute-user", - "x-api/users/unmute-user", - "x-api/users/get-muting" - ] - }, - { - "group": "Blocks", - "pages": [ - "x-api/users/blocks/introduction", { - "group": "Guides", + "group": "Affiliates", "pages": [ - "x-api/users/blocks/quickstart", - "x-api/users/blocks/integrate" + "x-api/users/get-affiliates" ] - }, - "x-api/users/get-blocking" + } ] }, { - "group": "Affiliates", - "pages": [ - "x-api/users/get-affiliates" - ] - } - ] - }, - { - "group": "Direct Messages", - "pages": [ - { - "group": "Manage", + "group": "Direct Messages", "pages": [ - "x-api/direct-messages/manage/introduction", { - "group": "Guides", + "group": "Manage", "pages": [ - "x-api/direct-messages/manage/quickstart", - "x-api/direct-messages/manage/integrate" + "x-api/direct-messages/manage/introduction", + { + "group": "Guides", + "pages": [ + "x-api/direct-messages/manage/quickstart", + "x-api/direct-messages/manage/integrate" + ] + }, + "x-api/direct-messages/create-dm-conversation", + "x-api/direct-messages/delete-dm-event", + "x-api/direct-messages/create-dm-message-by-participant-id", + "x-api/direct-messages/create-dm-message-by-conversation-id" ] }, - "x-api/direct-messages/create-dm-conversation", - "x-api/direct-messages/delete-dm-event", - "x-api/direct-messages/create-dm-message-by-participant-id", - "x-api/direct-messages/create-dm-message-by-conversation-id" - ] - }, - { - "group": "Lookup", - "pages": [ - "x-api/direct-messages/lookup/introduction", { - "group": "Guides", + "group": "Lookup", "pages": [ - "x-api/direct-messages/lookup/quickstart", - "x-api/direct-messages/lookup/integrate" + "x-api/direct-messages/lookup/introduction", + { + "group": "Guides", + "pages": [ + "x-api/direct-messages/lookup/quickstart", + "x-api/direct-messages/lookup/integrate" + ] + }, + "x-api/direct-messages/get-dm-events-for-a-dm-conversation", + "x-api/direct-messages/get-dm-events-for-a-dm-conversation-1", + "x-api/direct-messages/get-dm-events", + "x-api/direct-messages/get-dm-event-by-id" ] }, - "x-api/direct-messages/get-dm-events-for-a-dm-conversation", - "x-api/direct-messages/get-dm-events-for-a-dm-conversation-1", - "x-api/direct-messages/get-dm-events", - "x-api/direct-messages/get-dm-event-by-id" - ] - }, - { - "group": "Blocks", - "pages": [ - "x-api/direct-messages/blocks/introduction", - "x-api/users/block-dms", - "x-api/users/unblock-dms" - ] - } - ] - }, - { - "group": "Likes", - "pages": [ - "x-api/posts/likes/introduction", - { - "group": "Guides", - "pages": [ { - "group": "Quickstart", + "group": "Blocks", "pages": [ - "x-api/posts/likes/quickstart/likes-lookup", - "x-api/posts/likes/quickstart/manage-likes" + "x-api/direct-messages/blocks/introduction", + "x-api/users/block-dms", + "x-api/users/unblock-dms" ] } ] }, - "x-api/users/get-liked-posts", - "x-api/posts/get-liking-users", - "x-api/users/like-post", - "x-api/users/unlike-post" - ] - }, - { - "group": "Lists", - "pages": [ { - "group": "Lookup Lists", + "group": "Likes", "pages": [ - "x-api/lists/list-lookup/introduction", + "x-api/posts/likes/introduction", { "group": "Guides", "pages": [ - "x-api/lists/list-lookup/quickstart", - "x-api/lists/list-lookup/integrate" + { + "group": "Quickstart", + "pages": [ + "x-api/posts/likes/quickstart/likes-lookup", + "x-api/posts/likes/quickstart/manage-likes" + ] + } ] }, - "x-api/lists/get-list-by-id", - "x-api/users/get-followed-lists", - "x-api/users/get-owned-lists" + "x-api/users/get-liked-posts", + "x-api/posts/get-liking-users", + "x-api/users/like-post", + "x-api/users/unlike-post" ] }, { - "group": "Lookup List Posts", + "group": "Lists", "pages": [ - "x-api/lists/list-tweets/introduction", { - "group": "Guides", + "group": "Lookup Lists", "pages": [ - "x-api/lists/list-tweets/quickstart", - "x-api/lists/list-tweets/integrate" + "x-api/lists/list-lookup/introduction", + { + "group": "Guides", + "pages": [ + "x-api/lists/list-lookup/quickstart", + "x-api/lists/list-lookup/integrate" + ] + }, + "x-api/lists/get-list-by-id", + "x-api/users/get-followed-lists", + "x-api/users/get-owned-lists" ] }, - "x-api/lists/get-list-posts" - ] - }, - { - "group": "Manage Lists", - "pages": [ - "x-api/lists/manage-lists/introduction", { - "group": "Guides", + "group": "Lookup List Posts", "pages": [ - "x-api/lists/manage-lists/quickstart", - "x-api/lists/manage-lists/integrate" + "x-api/lists/list-tweets/introduction", + { + "group": "Guides", + "pages": [ + "x-api/lists/list-tweets/quickstart", + "x-api/lists/list-tweets/integrate" + ] + }, + "x-api/lists/get-list-posts" ] }, - "x-api/lists/create-list", - "x-api/lists/update-list", - "x-api/lists/delete-list", - "x-api/users/follow-list", - "x-api/users/unfollow-list" - ] - }, - { - "group": "List Members", - "pages": [ - "x-api/lists/list-members/introduction", { - "group": "Guides", + "group": "Manage Lists", "pages": [ + "x-api/lists/manage-lists/introduction", { - "group": "Quickstart", + "group": "Guides", "pages": [ - "x-api/lists/list-members/quickstart/overview", - "x-api/lists/list-members/quickstart/list-members-lookup", - "x-api/lists/list-members/quickstart/manage-list-members" + "x-api/lists/manage-lists/quickstart", + "x-api/lists/manage-lists/integrate" ] }, - "x-api/lists/list-members/integrate" + "x-api/lists/create-list", + "x-api/lists/update-list", + "x-api/lists/delete-list", + "x-api/users/follow-list", + "x-api/users/unfollow-list" ] }, { - "group": "Manage", + "group": "List Members", "pages": [ - "x-api/lists/add-list-member", - "x-api/lists/remove-list-member" + "x-api/lists/list-members/introduction", + { + "group": "Guides", + "pages": [ + { + "group": "Quickstart", + "pages": [ + "x-api/lists/list-members/quickstart/overview", + "x-api/lists/list-members/quickstart/list-members-lookup", + "x-api/lists/list-members/quickstart/manage-list-members" + ] + }, + "x-api/lists/list-members/integrate" + ] + }, + { + "group": "Manage", + "pages": [ + "x-api/lists/add-list-member", + "x-api/lists/remove-list-member" + ] + }, + { + "group": "Lookup", + "pages": [ + "x-api/users/get-list-memberships", + "x-api/lists/get-list-followers", + "x-api/lists/get-list-members" + ] + } ] }, { - "group": "Lookup", + "group": "Pinned Lists", "pages": [ - "x-api/users/get-list-memberships", - "x-api/lists/get-list-followers", - "x-api/lists/get-list-members" + "x-api/lists/pinned-lists/introduction", + { + "group": "Guides", + "pages": [ + { + "group": "Quickstart", + "pages": [ + "x-api/lists/pinned-lists/quickstart/overview", + "x-api/lists/pinned-lists/quickstart/pinned-list-lookup", + "x-api/lists/pinned-lists/quickstart/manage-pinned-lists" + ] + }, + "x-api/lists/pinned-lists/integrate" + ] + }, + "x-api/users/get-pinned-lists", + "x-api/users/pin-list", + "x-api/users/unpin-list" ] } ] }, { - "group": "Pinned Lists", + "group": "Spaces", "pages": [ - "x-api/lists/pinned-lists/introduction", + "x-api/spaces/introduction", { - "group": "Guides", + "group": "Spaces Lookup", "pages": [ + "x-api/spaces/lookup/introduction", { - "group": "Quickstart", + "group": "Guides", "pages": [ - "x-api/lists/pinned-lists/quickstart/overview", - "x-api/lists/pinned-lists/quickstart/pinned-list-lookup", - "x-api/lists/pinned-lists/quickstart/manage-pinned-lists" + "x-api/spaces/lookup/quickstart" ] }, - "x-api/lists/pinned-lists/integrate" + "x-api/spaces/get-spaces-by-ids", + "x-api/spaces/get-spaces-by-creator-ids", + "x-api/spaces/get-space-by-id", + "x-api/spaces/get-space-posts", + "x-api/spaces/get-space-ticket-buyers" ] }, - "x-api/users/get-pinned-lists", - "x-api/users/pin-list", - "x-api/users/unpin-list" - ] - } - ] - }, - { - "group": "Spaces", - "pages": [ - "x-api/spaces/introduction", - { - "group": "Spaces Lookup", - "pages": [ - "x-api/spaces/lookup/introduction", { - "group": "Guides", + "group": "Search Spaces", "pages": [ - "x-api/spaces/lookup/quickstart" + "x-api/spaces/search/introduction", + { + "group": "Guides", + "pages": [ + "x-api/spaces/search/quickstart" + ] + }, + "x-api/spaces/search-spaces" ] - }, - "x-api/spaces/get-spaces-by-ids", - "x-api/spaces/get-spaces-by-creator-ids", - "x-api/spaces/get-space-by-id", - "x-api/spaces/get-space-posts", - "x-api/spaces/get-space-ticket-buyers" + } ] }, { - "group": "Search Spaces", + "group": "Communities", "pages": [ - "x-api/spaces/search/introduction", { - "group": "Guides", + "group": "Communities Lookup", "pages": [ - "x-api/spaces/search/quickstart" + "x-api/communities/lookup/introduction", + "x-api/communities/get-community-by-id" ] }, - "x-api/spaces/search-spaces" - ] - } - ] - }, - { - "group": "Communities", - "pages": [ - { - "group": "Communities Lookup", - "pages": [ - "x-api/communities/lookup/introduction", - "x-api/communities/get-community-by-id" + { + "group": "Search Communities", + "pages": [ + "x-api/communities/search/introduction", + "x-api/communities/search-communities" + ] + } ] }, { - "group": "Search Communities", + "group": "Community Notes", "pages": [ - "x-api/communities/search/introduction", - "x-api/communities/search-communities" + "x-api/community-notes/introduction", + "x-api/community-notes/quickstart", + "x-api/community-notes/search-for-posts-eligible-for-community-notes", + "x-api/community-notes/search-for-community-notes-written", + "x-api/community-notes/create-a-community-note", + "x-api/community-notes/delete-a-community-note", + "x-api/community-notes/evaluate-a-community-note" ] - } - ] - }, - { - "group": "Community Notes", - "pages": [ - "x-api/community-notes/introduction", - "x-api/community-notes/quickstart", - "x-api/community-notes/search-for-posts-eligible-for-community-notes", - "x-api/community-notes/search-for-community-notes-written", - "x-api/community-notes/create-a-community-note", - "x-api/community-notes/delete-a-community-note", - "x-api/community-notes/evaluate-a-community-note" - ] - }, - { - "group": "Trends", - "pages": [ + }, { "group": "Trends", "pages": [ - "x-api/trends/trends-by-woeid/introduction", - "x-api/trends/get-trends-by-woeid" + { + "group": "Trends", + "pages": [ + "x-api/trends/trends-by-woeid/introduction", + "x-api/trends/get-trends-by-woeid" + ] + }, + { + "group": "Personalized Trends", + "pages": [ + "x-api/trends/personalized-trends/introduction", + "x-api/trends/get-personalized-trends" + ] + } ] }, { - "group": "Personalized Trends", + "group": "News", "pages": [ - "x-api/trends/personalized-trends/introduction", - "x-api/trends/get-personalized-trends" + "x-api/news/introduction", + "x-api/news/get-news-stories-by-id", + "x-api/news/search-news" ] - } - ] - }, - { - "group": "News", - "pages": [ - "x-api/news/introduction", - "x-api/news/get-news-stories-by-id", - "x-api/news/search-news" - ] - }, - { - "group": "Media", - "pages": [ - "x-api/media/introduction", + }, { - "group": "Upload", + "group": "Media", "pages": [ + "x-api/media/introduction", { - "group": "Guides", + "group": "Upload", "pages": [ - "x-api/media/quickstart/best-practices", - "x-api/media/quickstart/media-upload-chunked" + { + "group": "Guides", + "pages": [ + "x-api/media/quickstart/best-practices", + "x-api/media/quickstart/media-upload-chunked" + ] + }, + "x-api/media/upload-media", + "x-api/media/initialize-media-upload", + "x-api/media/append-media-upload", + "x-api/media/finalize-media-upload", + "x-api/media/get-media-upload-status" ] }, - "x-api/media/upload-media", - "x-api/media/initialize-media-upload", - "x-api/media/append-media-upload", - "x-api/media/finalize-media-upload", - "x-api/media/get-media-upload-status" + { + "group": "Metadata", + "pages": [ + "x-api/media/create-media-metadata", + "x-api/media/create-media-subtitles", + "x-api/media/delete-media-subtitles" + ] + } ] }, { - "group": "Metadata", + "group": "X Activity", "pages": [ - "x-api/media/create-media-metadata", - "x-api/media/create-media-subtitles", - "x-api/media/delete-media-subtitles" + "x-api/activity/introduction", + "x-api/activity/quickstart", + "x-api/activity/activity-stream", + "x-api/activity/create-x-activity-subscription", + "x-api/activity/deletes-x-activity-subscription", + "x-api/activity/delete-x-activity-subscriptions-by-ids", + "x-api/activity/get-x-activity-subscriptions", + "x-api/activity/update-x-activity-subscription" ] - } - ] - }, - { - "group": "X Activity", - "pages": [ - "x-api/activity/introduction", - "x-api/activity/quickstart", - "x-api/activity/activity-stream", - "x-api/activity/create-x-activity-subscription", - "x-api/activity/deletes-x-activity-subscription", - "x-api/activity/delete-x-activity-subscriptions-by-ids", - "x-api/activity/get-x-activity-subscriptions", - "x-api/activity/update-x-activity-subscription" - ] - }, - { - "group": "Usage", - "pages": [ - "x-api/usage/introduction", - "x-api/usage/get-usage" - ] - }, - { - "group": "Stream Connections", - "pages": [ - "x-api/connections/introduction", - "x-api/connections/get-connection-history", - "x-api/connections/terminate-connections-by-endpoint", - "x-api/connections/terminate-multiple-connections", - "x-api/connections/terminate-all-connections" - ] - }, - { - "group": "Compliance", - "pages": [ + }, + { + "group": "Usage", + "pages": [ + "x-api/usage/introduction", + "x-api/usage/get-usage" + ] + }, + { + "group": "Stream Connections", + "pages": [ + "x-api/connections/introduction", + "x-api/connections/get-connection-history", + "x-api/connections/terminate-connections-by-endpoint", + "x-api/connections/terminate-multiple-connections", + "x-api/connections/terminate-all-connections" + ] + }, { - "group": "Batch Compliance", + "group": "Compliance", "pages": [ - "x-api/compliance/batch-compliance/introduction", { - "group": "Guides", + "group": "Batch Compliance", "pages": [ - "x-api/compliance/batch-compliance/quickstart", - "x-api/compliance/batch-compliance/integrate" + "x-api/compliance/batch-compliance/introduction", + { + "group": "Guides", + "pages": [ + "x-api/compliance/batch-compliance/quickstart", + "x-api/compliance/batch-compliance/integrate" + ] + }, + "x-api/compliance/get-compliance-jobs", + "x-api/compliance/create-compliance-job", + "x-api/compliance/get-compliance-job-by-id" ] }, - "x-api/compliance/get-compliance-jobs", - "x-api/compliance/create-compliance-job", - "x-api/compliance/get-compliance-job-by-id" + { + "group": "Compliance streams", + "pages": [ + "x-api/compliance/streams/introduction", + "x-api/stream/stream-likes-compliance-data", + "x-api/stream/stream-posts-compliance-data", + "x-api/stream/stream-users-compliance-data" + ] + } ] }, { - "group": "Compliance streams", + "group": "Webhooks", "pages": [ - "x-api/compliance/streams/introduction", - "x-api/stream/stream-likes-compliance-data", - "x-api/stream/stream-posts-compliance-data", - "x-api/stream/stream-users-compliance-data" + "x-api/webhooks/introduction", + "x-api/webhooks/quickstart", + "x-api/webhooks/create-webhook", + "x-api/webhooks/delete-webhook", + "x-api/webhooks/get-webhook", + "x-api/webhooks/validate-webhook", + "x-api/webhooks/create-replay-job-for-webhook" ] } ] }, { - "group": "Webhooks", - "pages": [ - "x-api/webhooks/introduction", - "x-api/webhooks/quickstart", - "x-api/webhooks/create-webhook", - "x-api/webhooks/delete-webhook", - "x-api/webhooks/get-webhook", - "x-api/webhooks/validate-webhook", - "x-api/webhooks/create-replay-job-for-webhook" - ] - }, - { - "group": "Enterprise", - "pages": [ + "dropdown": "Enterprise", + "icon": "building", + "groups": [ { "group": "Analytics", "pages": [ @@ -978,11 +973,26 @@ ] }, { - "tab": "X Ads API", - "hidden": true, + "tab": "Changelog", + "groups": [ + { + "group": "Changelog", + "pages": [ + "changelog" + ] + } + ] + } + ] + }, + { + "product": "Ads API", + "tabs": [ + { + "tab": "API Reference", "groups": [ { - "group": "X Ads API", + "group": "Overview", "pages": [ "x-ads-api/introduction", { @@ -1035,921 +1045,161 @@ ] } ] - }, + } + ] + }, + { + "product": "Enterprise", + "hidden": true, + "groups": [ { - "tab": "Enterprise", - "groups": [ + "group": "Overview", + "pages": [ + "enterprise-api/introduction" + ] + } + ] + }, + { + "product": "Python XDK", + "hidden": true, + "pages": [ + "xdks/python/overview", + "xdks/python/install", + "xdks/python/quickstart", + "xdks/python/authentication", + "xdks/python/pagination", + "xdks/python/streaming", + { + "group": "API Reference", + "pages": [ + "xdks/python/reference/modules", { - "group": "Overview", + "group": "Clients", "pages": [ - "enterprise-api/introduction" + {"group": "Account Activity", "pages": ["xdks/python/reference/xdk.account_activity.client"]}, + {"group": "Activity", "pages": ["xdks/python/reference/xdk.activity.client"]}, + {"group": "Client", "pages": ["xdks/python/reference/xdk.client"]}, + {"group": "Communities", "pages": ["xdks/python/reference/xdk.communities.client"]}, + {"group": "Community Notes", "pages": ["xdks/python/reference/xdk.community_notes.client"]}, + {"group": "Compliance", "pages": ["xdks/python/reference/xdk.compliance.client"]}, + {"group": "Connections", "pages": ["xdks/python/reference/xdk.connections.client"]}, + {"group": "Direct Messages", "pages": ["xdks/python/reference/xdk.direct_messages.client"]}, + {"group": "General", "pages": ["xdks/python/reference/xdk.general.client"]}, + {"group": "Lists", "pages": ["xdks/python/reference/xdk.lists.client"]}, + {"group": "Media", "pages": ["xdks/python/reference/xdk.media.client"]}, + {"group": "News", "pages": ["xdks/python/reference/xdk.news.client"]}, + {"group": "Posts", "pages": ["xdks/python/reference/xdk.posts.client"]}, + {"group": "Spaces", "pages": ["xdks/python/reference/xdk.spaces.client"]}, + {"group": "Stream", "pages": ["xdks/python/reference/xdk.stream.client"]}, + {"group": "Trends", "pages": ["xdks/python/reference/xdk.trends.client"]}, + {"group": "Usage", "pages": ["xdks/python/reference/xdk.usage.client"]}, + {"group": "Users", "pages": ["xdks/python/reference/xdk.users.client"]}, + {"group": "Webhooks", "pages": ["xdks/python/reference/xdk.webhooks.client"]} ] - } - ], - "hidden": true - }, - { - "tab": "Tutorials", - "groups": [ + }, { - "group": "Tutorials", + "group": "Models", "pages": [ - "tutorials", - "tutorials/explore-a-users-posts", - "tutorials/postman-getting-started", - "tutorials/getting-historical-posts-using-the-full-archive-search-endpoint" + {"group": "Account Activity", "pages": ["xdks/python/reference/xdk.account_activity.models"]}, + {"group": "Activity", "pages": ["xdks/python/reference/xdk.activity.models"]}, + {"group": "Communities", "pages": ["xdks/python/reference/xdk.communities.models"]}, + {"group": "Community Notes", "pages": ["xdks/python/reference/xdk.community_notes.models"]}, + {"group": "Compliance", "pages": ["xdks/python/reference/xdk.compliance.models"]}, + {"group": "Connections", "pages": ["xdks/python/reference/xdk.connections.models"]}, + {"group": "Direct Messages", "pages": ["xdks/python/reference/xdk.direct_messages.models"]}, + {"group": "General", "pages": ["xdks/python/reference/xdk.general.models"]}, + {"group": "Lists", "pages": ["xdks/python/reference/xdk.lists.models"]}, + {"group": "Media", "pages": ["xdks/python/reference/xdk.media.models"]}, + {"group": "News", "pages": ["xdks/python/reference/xdk.news.models"]}, + {"group": "Posts", "pages": ["xdks/python/reference/xdk.posts.models"]}, + {"group": "Spaces", "pages": ["xdks/python/reference/xdk.spaces.models"]}, + {"group": "Stream", "pages": ["xdks/python/reference/xdk.stream.models"]}, + {"group": "Trends", "pages": ["xdks/python/reference/xdk.trends.models"]}, + {"group": "Usage", "pages": ["xdks/python/reference/xdk.usage.models"]}, + {"group": "Users", "pages": ["xdks/python/reference/xdk.users.models"]}, + {"group": "Webhooks", "pages": ["xdks/python/reference/xdk.webhooks.models"]} ] - } - ] - }, - { - "tab": "Success Stories", - "groups": [ + }, { - "group": "Success Stories", + "group": "Core", "pages": [ - "success-stories" + {"group": "Account Activity", "pages": ["xdks/python/reference/xdk.account_activity"]}, + {"group": "Activity", "pages": ["xdks/python/reference/xdk.activity"]}, + {"group": "Communities", "pages": ["xdks/python/reference/xdk.communities"]}, + {"group": "Community Notes", "pages": ["xdks/python/reference/xdk.community_notes"]}, + {"group": "Compliance", "pages": ["xdks/python/reference/xdk.compliance"]}, + {"group": "Connections", "pages": ["xdks/python/reference/xdk.connections"]}, + {"group": "Direct Messages", "pages": ["xdks/python/reference/xdk.direct_messages"]}, + {"group": "General", "pages": ["xdks/python/reference/xdk.general"]}, + {"group": "Lists", "pages": ["xdks/python/reference/xdk.lists"]}, + {"group": "Media", "pages": ["xdks/python/reference/xdk.media"]}, + {"group": "News", "pages": ["xdks/python/reference/xdk.news"]}, + {"group": "Oauth1 Auth", "pages": ["xdks/python/reference/xdk.oauth1_auth"]}, + {"group": "Oauth2 Auth", "pages": ["xdks/python/reference/xdk.oauth2_auth"]}, + {"group": "Paginator", "pages": ["xdks/python/reference/xdk.paginator"]}, + {"group": "Posts", "pages": ["xdks/python/reference/xdk.posts"]}, + {"group": "Spaces", "pages": ["xdks/python/reference/xdk.spaces"]}, + {"group": "Stream", "pages": ["xdks/python/reference/xdk.stream"]}, + {"group": "Streaming", "pages": ["xdks/python/reference/xdk.streaming"]}, + {"group": "Trends", "pages": ["xdks/python/reference/xdk.trends"]}, + {"group": "Usage", "pages": ["xdks/python/reference/xdk.usage"]}, + {"group": "Users", "pages": ["xdks/python/reference/xdk.users"]}, + {"group": "Webhooks", "pages": ["xdks/python/reference/xdk.webhooks"]}, + {"group": "Xdk", "pages": ["xdks/python/reference/xdk"]} ] } ] - }, + } + ] + }, + { + "product": "TypeScript XDK", + "hidden": true, + "pages": [ + "xdks/typescript/overview", + "xdks/typescript/install", + "xdks/typescript/authentication", + "xdks/typescript/pagination", + "xdks/typescript/streaming", { - "tab": "Status", - "groups": [ + "group": "API Reference", + "pages": [ + "xdks/typescript/reference/modules", { - "group": "Status", + "group": "Interfaces", "pages": [ - "status" + {"group": "Client", "pages": ["xdks/typescript/reference/interfaces/ClientConfig"]}, + {"group": "Http", "pages": ["xdks/typescript/reference/interfaces/HttpClientRequestOptions", "xdks/typescript/reference/interfaces/HttpResponse"]}, + {"group": "Misc", "pages": ["xdks/typescript/reference/interfaces/ApiResponse", "xdks/typescript/reference/interfaces/PaginatedResponse", "xdks/typescript/reference/interfaces/PaginationMeta", "xdks/typescript/reference/interfaces/RequestOptions", "xdks/typescript/reference/interfaces/Schemas.ActivityStreamingResponse", "xdks/typescript/reference/interfaces/Schemas.ActivitySubscription", "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateRequest", "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateResponse", "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionFilter", "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionGetResponse", "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateRequest", "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateResponse", "xdks/typescript/reference/interfaces/Schemas.AddOrDeleteRulesResponse", "xdks/typescript/reference/interfaces/Schemas.AddRulesRequest", "xdks/typescript/reference/interfaces/Schemas.AllowDownloadStatus", "xdks/typescript/reference/interfaces/Schemas.AltText", "xdks/typescript/reference/interfaces/Schemas.Analytics", "xdks/typescript/reference/interfaces/Schemas.AppRulesCount", "xdks/typescript/reference/interfaces/Schemas.AudiencePolicy", "xdks/typescript/reference/interfaces/Schemas.BookmarkAddRequest", "xdks/typescript/reference/interfaces/Schemas.BookmarkFolderPostsResponse", "xdks/typescript/reference/interfaces/Schemas.BookmarkFoldersResponse", "xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse", "xdks/typescript/reference/interfaces/Schemas.CashtagFields", "xdks/typescript/reference/interfaces/Schemas.ClientAppUsage", "xdks/typescript/reference/interfaces/Schemas.Community", "xdks/typescript/reference/interfaces/Schemas.ComplianceJob", "xdks/typescript/reference/interfaces/Schemas.Connection", "xdks/typescript/reference/interfaces/Schemas.ContentExpiration", "xdks/typescript/reference/interfaces/Schemas.ContextAnnotation", "xdks/typescript/reference/interfaces/Schemas.ContextAnnotationDomainFields", "xdks/typescript/reference/interfaces/Schemas.ContextAnnotationEntityFields", "xdks/typescript/reference/interfaces/Schemas.CreateAttachmentsMessageRequest", "xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobRequest", "xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobResponse", "xdks/typescript/reference/interfaces/Schemas.CreateDmConversationRequest", "xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse", "xdks/typescript/reference/interfaces/Schemas.CreateNoteRequest", "xdks/typescript/reference/interfaces/Schemas.CreateNoteResponse", "xdks/typescript/reference/interfaces/Schemas.CreateTextMessageRequest", "xdks/typescript/reference/interfaces/Schemas.DeleteDmResponse", "xdks/typescript/reference/interfaces/Schemas.DeleteNoteResponse", "xdks/typescript/reference/interfaces/Schemas.DeleteRulesRequest", "xdks/typescript/reference/interfaces/Schemas.DmEvent", "xdks/typescript/reference/interfaces/Schemas.DmMediaAttachment", "xdks/typescript/reference/interfaces/Schemas.DomainRestrictions", "xdks/typescript/reference/interfaces/Schemas.Engagement", "xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveExclusive", "xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveInclusive", "xdks/typescript/reference/interfaces/Schemas.Error", "xdks/typescript/reference/interfaces/Schemas.EvaluateNoteRequest", "xdks/typescript/reference/interfaces/Schemas.EvaluateNoteResponse", "xdks/typescript/reference/interfaces/Schemas.Expansions", "xdks/typescript/reference/interfaces/Schemas.FilteredStreamingTweetResponse", "xdks/typescript/reference/interfaces/Schemas.FollowActivityResponsePayload", "xdks/typescript/reference/interfaces/Schemas.FoundMediaOrigin", "xdks/typescript/reference/interfaces/Schemas.FullTextEntities", "xdks/typescript/reference/interfaces/Schemas.Geo", "xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesIdResponse", "xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesSearchResponse", "xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsIdResponse", "xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2ConnectionsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsIdDmEventsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsWithParticipantIdDmEventsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2DmEventsEventIdResponse", "xdks/typescript/reference/interfaces/Schemas.Get2DmEventsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidContactResponse", "xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidPayment_networksResponse", "xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidResponse", "xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidTransactionsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2FdxCustomersCurrentResponse", "xdks/typescript/reference/interfaces/Schemas.Get2Insights28hrResponse", "xdks/typescript/reference/interfaces/Schemas.Get2InsightsHistoricalResponse", "xdks/typescript/reference/interfaces/Schemas.Get2LikesFirehoseStreamResponse", "xdks/typescript/reference/interfaces/Schemas.Get2LikesSample10StreamResponse", "xdks/typescript/reference/interfaces/Schemas.Get2ListsIdFollowersResponse", "xdks/typescript/reference/interfaces/Schemas.Get2ListsIdMembersResponse", "xdks/typescript/reference/interfaces/Schemas.Get2ListsIdResponse", "xdks/typescript/reference/interfaces/Schemas.Get2ListsIdTweetsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2MediaAnalyticsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2MediaMediaKeyResponse", "xdks/typescript/reference/interfaces/Schemas.Get2MediaResponse", "xdks/typescript/reference/interfaces/Schemas.Get2NewsIdResponse", "xdks/typescript/reference/interfaces/Schemas.Get2NewsSearchResponse", "xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchNotesWrittenResponse", "xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchPostsEligibleForNotesResponse", "xdks/typescript/reference/interfaces/Schemas.Get2SpacesByCreatorIdsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdBuyersResponse", "xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdResponse", "xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdTweetsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2SpacesResponse", "xdks/typescript/reference/interfaces/Schemas.Get2SpacesSearchResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TrendsByWoeidWoeidResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsAnalyticsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsAllResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsRecentResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangEnResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangJaResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangKoResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangPtResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdLikingUsersResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdQuoteTweetsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetedByResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSample10StreamResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSampleStreamResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchAllResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchRecentResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamResponse", "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamRulesCountsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsageTweetsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersByResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersByUsernameUsernameResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBlockingResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBookmarksResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowedListsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowersResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowingResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdLikedTweetsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdListMembershipsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMentionsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMutingResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdOwnedListsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdPinnedListsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTimelinesReverseChronologicalResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTweetsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersMeResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersPersonalizedTrendsResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersRepostsOfMeResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersResponse", "xdks/typescript/reference/interfaces/Schemas.Get2UsersSearchResponse", "xdks/typescript/reference/interfaces/Schemas.Get2WebhooksResponse", "xdks/typescript/reference/interfaces/Schemas.HashtagFields", "xdks/typescript/reference/interfaces/Schemas.KillAllConnectionsResponse", "xdks/typescript/reference/interfaces/Schemas.LikeComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.LikeWithTweetAuthor", "xdks/typescript/reference/interfaces/Schemas.List", "xdks/typescript/reference/interfaces/Schemas.ListAddUserRequest", "xdks/typescript/reference/interfaces/Schemas.ListCreateRequest", "xdks/typescript/reference/interfaces/Schemas.ListCreateResponse", "xdks/typescript/reference/interfaces/Schemas.ListDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.ListFollowedRequest", "xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse", "xdks/typescript/reference/interfaces/Schemas.ListMutateResponse", "xdks/typescript/reference/interfaces/Schemas.ListPinnedRequest", "xdks/typescript/reference/interfaces/Schemas.ListPinnedResponse", "xdks/typescript/reference/interfaces/Schemas.ListUnpinResponse", "xdks/typescript/reference/interfaces/Schemas.ListUpdateRequest", "xdks/typescript/reference/interfaces/Schemas.ListUpdateResponse", "xdks/typescript/reference/interfaces/Schemas.ManagementInfo", "xdks/typescript/reference/interfaces/Schemas.Media", "xdks/typescript/reference/interfaces/Schemas.MediaAnalytics", "xdks/typescript/reference/interfaces/Schemas.MediaMetrics", "xdks/typescript/reference/interfaces/Schemas.MediaTimestampedMetrics", "xdks/typescript/reference/interfaces/Schemas.MediaUploadAppendResponse", "xdks/typescript/reference/interfaces/Schemas.MediaUploadConfigRequest", "xdks/typescript/reference/interfaces/Schemas.MediaUploadRequestOneShot", "xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse", "xdks/typescript/reference/interfaces/Schemas.MentionFields", "xdks/typescript/reference/interfaces/Schemas.MetadataCreateRequest", "xdks/typescript/reference/interfaces/Schemas.MetadataCreateResponse", "xdks/typescript/reference/interfaces/Schemas.Metrics", "xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse", "xdks/typescript/reference/interfaces/Schemas.MuteUserRequest", "xdks/typescript/reference/interfaces/Schemas.News", "xdks/typescript/reference/interfaces/Schemas.NewsActivityResponsePayload", "xdks/typescript/reference/interfaces/Schemas.Note", "xdks/typescript/reference/interfaces/Schemas.NoteInfo", "xdks/typescript/reference/interfaces/Schemas.NoteTestResult", "xdks/typescript/reference/interfaces/Schemas.PersonalizedTrend", "xdks/typescript/reference/interfaces/Schemas.Place", "xdks/typescript/reference/interfaces/Schemas.PlaidAccount", "xdks/typescript/reference/interfaces/Schemas.PlaidAccountContact", "xdks/typescript/reference/interfaces/Schemas.PlaidAccountPaymentNetwork", "xdks/typescript/reference/interfaces/Schemas.PlaidAccountTransaction", "xdks/typescript/reference/interfaces/Schemas.PlaidAddress", "xdks/typescript/reference/interfaces/Schemas.PlaidCurrency", "xdks/typescript/reference/interfaces/Schemas.PlaidCustomer", "xdks/typescript/reference/interfaces/Schemas.PlaidName", "xdks/typescript/reference/interfaces/Schemas.PlaidTelephone", "xdks/typescript/reference/interfaces/Schemas.Point", "xdks/typescript/reference/interfaces/Schemas.Poll", "xdks/typescript/reference/interfaces/Schemas.PollOption", "xdks/typescript/reference/interfaces/Schemas.PreviewImage", "xdks/typescript/reference/interfaces/Schemas.Problem", "xdks/typescript/reference/interfaces/Schemas.ProcessingInfo", "xdks/typescript/reference/interfaces/Schemas.ProfileUpdateActivityResponsePayload", "xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse", "xdks/typescript/reference/interfaces/Schemas.Rule", "xdks/typescript/reference/interfaces/Schemas.RuleNoId", "xdks/typescript/reference/interfaces/Schemas.RulesCount", "xdks/typescript/reference/interfaces/Schemas.RulesLookupResponse", "xdks/typescript/reference/interfaces/Schemas.RulesResponseMetadata", "xdks/typescript/reference/interfaces/Schemas.SearchCount", "xdks/typescript/reference/interfaces/Schemas.SensitiveMediaWarning", "xdks/typescript/reference/interfaces/Schemas.SharedInfo", "xdks/typescript/reference/interfaces/Schemas.Space", "xdks/typescript/reference/interfaces/Schemas.Sticker", "xdks/typescript/reference/interfaces/Schemas.StickerInfo", "xdks/typescript/reference/interfaces/Schemas.StreamingLikeResponseV2", "xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse", "xdks/typescript/reference/interfaces/Schemas.SubscriptionsCountGetResponse", "xdks/typescript/reference/interfaces/Schemas.SubscriptionsCreateResponse", "xdks/typescript/reference/interfaces/Schemas.SubscriptionsDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.SubscriptionsGetResponse", "xdks/typescript/reference/interfaces/Schemas.SubscriptionsListGetResponse", "xdks/typescript/reference/interfaces/Schemas.Subtitles", "xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateRequest", "xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateResponse", "xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteRequest", "xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.TimestampedMetrics", "xdks/typescript/reference/interfaces/Schemas.Topic", "xdks/typescript/reference/interfaces/Schemas.Trend", "xdks/typescript/reference/interfaces/Schemas.Tweet", "xdks/typescript/reference/interfaces/Schemas.TweetComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.TweetCreateRequest", "xdks/typescript/reference/interfaces/Schemas.TweetCreateResponse", "xdks/typescript/reference/interfaces/Schemas.TweetDeleteComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.TweetDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.TweetDropComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceObjectSchema", "xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.TweetHideRequest", "xdks/typescript/reference/interfaces/Schemas.TweetHideResponse", "xdks/typescript/reference/interfaces/Schemas.TweetNotice", "xdks/typescript/reference/interfaces/Schemas.TweetNoticeSchema", "xdks/typescript/reference/interfaces/Schemas.TweetTakedownComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.TweetUndropComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.TweetUnviewable", "xdks/typescript/reference/interfaces/Schemas.TweetUnviewableSchema", "xdks/typescript/reference/interfaces/Schemas.TweetWithheld", "xdks/typescript/reference/interfaces/Schemas.TweetWithheldComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UnlikeComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UploadSource", "xdks/typescript/reference/interfaces/Schemas.UrlFields", "xdks/typescript/reference/interfaces/Schemas.UrlImage", "xdks/typescript/reference/interfaces/Schemas.Usage", "xdks/typescript/reference/interfaces/Schemas.UsageFields", "xdks/typescript/reference/interfaces/Schemas.User", "xdks/typescript/reference/interfaces/Schemas.UserComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UserDeleteComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UserProfileModificationComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UserProfileModificationObjectSchema", "xdks/typescript/reference/interfaces/Schemas.UserProtectComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UserScrubGeoObjectSchema", "xdks/typescript/reference/interfaces/Schemas.UserScrubGeoSchema", "xdks/typescript/reference/interfaces/Schemas.UserSuspendComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UserTakedownComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UserUndeleteComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UserUnprotectComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UserUnsuspendComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UserWithheld", "xdks/typescript/reference/interfaces/Schemas.UserWithheldComplianceSchema", "xdks/typescript/reference/interfaces/Schemas.UsersDMBlockCreateResponse", "xdks/typescript/reference/interfaces/Schemas.UsersDMUnBlockCreateResponse", "xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateRequest", "xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateResponse", "xdks/typescript/reference/interfaces/Schemas.UsersFollowingDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateRequest", "xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateResponse", "xdks/typescript/reference/interfaces/Schemas.UsersLikesDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateRequest", "xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateResponse", "xdks/typescript/reference/interfaces/Schemas.UsersRetweetsDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.Variant", "xdks/typescript/reference/interfaces/Schemas.WebhookConfig", "xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateRequest", "xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateResponse", "xdks/typescript/reference/interfaces/Schemas.WebhookConfigDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.WebhookConfigPutResponse", "xdks/typescript/reference/interfaces/Schemas.WebhookLinksCreateResponse", "xdks/typescript/reference/interfaces/Schemas.WebhookLinksDeleteResponse", "xdks/typescript/reference/interfaces/Schemas.WebhookLinksGetResponse", "xdks/typescript/reference/interfaces/Schemas.WebhookReplayCreateRequest"]} ] - } - ] - }, - { - "tab": "Changelog", - "groups": [ + }, { - "group": "Changelog", + "group": "Classes", "pages": [ - "changelog" - ] - } - ] - }, - { - "tab": "Python XDK", - "hidden": true, - "pages": [ - "xdks/python/overview", - "xdks/python/install", - "xdks/python/quickstart", - "xdks/python/authentication", - "xdks/python/pagination", - "xdks/python/streaming", - { - "group": "API Reference", - "pages": [ - "xdks/python/reference/modules", - { - "group": "Clients", - "pages": [ - { - "group": "Account Activity", - "pages": [ - "xdks/python/reference/xdk.account_activity.client" - ] - }, - { - "group": "Activity", - "pages": [ - "xdks/python/reference/xdk.activity.client" - ] - }, - { - "group": "Client", - "pages": [ - "xdks/python/reference/xdk.client" - ] - }, - { - "group": "Communities", - "pages": [ - "xdks/python/reference/xdk.communities.client" - ] - }, - { - "group": "Community Notes", - "pages": [ - "xdks/python/reference/xdk.community_notes.client" - ] - }, - { - "group": "Compliance", - "pages": [ - "xdks/python/reference/xdk.compliance.client" - ] - }, - { - "group": "Connections", - "pages": [ - "xdks/python/reference/xdk.connections.client" - ] - }, - { - "group": "Direct Messages", - "pages": [ - "xdks/python/reference/xdk.direct_messages.client" - ] - }, - { - "group": "General", - "pages": [ - "xdks/python/reference/xdk.general.client" - ] - }, - { - "group": "Lists", - "pages": [ - "xdks/python/reference/xdk.lists.client" - ] - }, - { - "group": "Media", - "pages": [ - "xdks/python/reference/xdk.media.client" - ] - }, - { - "group": "News", - "pages": [ - "xdks/python/reference/xdk.news.client" - ] - }, - { - "group": "Posts", - "pages": [ - "xdks/python/reference/xdk.posts.client" - ] - }, - { - "group": "Spaces", - "pages": [ - "xdks/python/reference/xdk.spaces.client" - ] - }, - { - "group": "Stream", - "pages": [ - "xdks/python/reference/xdk.stream.client" - ] - }, - { - "group": "Trends", - "pages": [ - "xdks/python/reference/xdk.trends.client" - ] - }, - { - "group": "Usage", - "pages": [ - "xdks/python/reference/xdk.usage.client" - ] - }, - { - "group": "Users", - "pages": [ - "xdks/python/reference/xdk.users.client" - ] - }, - { - "group": "Webhooks", - "pages": [ - "xdks/python/reference/xdk.webhooks.client" - ] - } - ] - }, - { - "group": "Models", - "pages": [ - { - "group": "Account Activity", - "pages": [ - "xdks/python/reference/xdk.account_activity.models" - ] - }, - { - "group": "Activity", - "pages": [ - "xdks/python/reference/xdk.activity.models" - ] - }, - { - "group": "Communities", - "pages": [ - "xdks/python/reference/xdk.communities.models" - ] - }, - { - "group": "Community Notes", - "pages": [ - "xdks/python/reference/xdk.community_notes.models" - ] - }, - { - "group": "Compliance", - "pages": [ - "xdks/python/reference/xdk.compliance.models" - ] - }, - { - "group": "Connections", - "pages": [ - "xdks/python/reference/xdk.connections.models" - ] - }, - { - "group": "Direct Messages", - "pages": [ - "xdks/python/reference/xdk.direct_messages.models" - ] - }, - { - "group": "General", - "pages": [ - "xdks/python/reference/xdk.general.models" - ] - }, - { - "group": "Lists", - "pages": [ - "xdks/python/reference/xdk.lists.models" - ] - }, - { - "group": "Media", - "pages": [ - "xdks/python/reference/xdk.media.models" - ] - }, - { - "group": "News", - "pages": [ - "xdks/python/reference/xdk.news.models" - ] - }, - { - "group": "Posts", - "pages": [ - "xdks/python/reference/xdk.posts.models" - ] - }, - { - "group": "Spaces", - "pages": [ - "xdks/python/reference/xdk.spaces.models" - ] - }, - { - "group": "Stream", - "pages": [ - "xdks/python/reference/xdk.stream.models" - ] - }, - { - "group": "Trends", - "pages": [ - "xdks/python/reference/xdk.trends.models" - ] - }, - { - "group": "Usage", - "pages": [ - "xdks/python/reference/xdk.usage.models" - ] - }, - { - "group": "Users", - "pages": [ - "xdks/python/reference/xdk.users.models" - ] - }, - { - "group": "Webhooks", - "pages": [ - "xdks/python/reference/xdk.webhooks.models" - ] - } - ] - }, - { - "group": "Core", - "pages": [ - { - "group": "Account Activity", - "pages": [ - "xdks/python/reference/xdk.account_activity" - ] - }, - { - "group": "Activity", - "pages": [ - "xdks/python/reference/xdk.activity" - ] - }, - { - "group": "Communities", - "pages": [ - "xdks/python/reference/xdk.communities" - ] - }, - { - "group": "Community Notes", - "pages": [ - "xdks/python/reference/xdk.community_notes" - ] - }, - { - "group": "Compliance", - "pages": [ - "xdks/python/reference/xdk.compliance" - ] - }, - { - "group": "Connections", - "pages": [ - "xdks/python/reference/xdk.connections" - ] - }, - { - "group": "Direct Messages", - "pages": [ - "xdks/python/reference/xdk.direct_messages" - ] - }, - { - "group": "General", - "pages": [ - "xdks/python/reference/xdk.general" - ] - }, - { - "group": "Lists", - "pages": [ - "xdks/python/reference/xdk.lists" - ] - }, - { - "group": "Media", - "pages": [ - "xdks/python/reference/xdk.media" - ] - }, - { - "group": "News", - "pages": [ - "xdks/python/reference/xdk.news" - ] - }, - { - "group": "Oauth1 Auth", - "pages": [ - "xdks/python/reference/xdk.oauth1_auth" - ] - }, - { - "group": "Oauth2 Auth", - "pages": [ - "xdks/python/reference/xdk.oauth2_auth" - ] - }, - { - "group": "Paginator", - "pages": [ - "xdks/python/reference/xdk.paginator" - ] - }, - { - "group": "Posts", - "pages": [ - "xdks/python/reference/xdk.posts" - ] - }, - { - "group": "Spaces", - "pages": [ - "xdks/python/reference/xdk.spaces" - ] - }, - { - "group": "Stream", - "pages": [ - "xdks/python/reference/xdk.stream" - ] - }, - { - "group": "Streaming", - "pages": [ - "xdks/python/reference/xdk.streaming" - ] - }, - { - "group": "Trends", - "pages": [ - "xdks/python/reference/xdk.trends" - ] - }, - { - "group": "Usage", - "pages": [ - "xdks/python/reference/xdk.usage" - ] - }, - { - "group": "Users", - "pages": [ - "xdks/python/reference/xdk.users" - ] - }, - { - "group": "Webhooks", - "pages": [ - "xdks/python/reference/xdk.webhooks" - ] - }, - { - "group": "Xdk", - "pages": [ - "xdks/python/reference/xdk" - ] - } - ] - } - ] - } - ] - }, - { - "tab": "TypeScript XDK", - "hidden": true, - "pages": [ - "xdks/typescript/overview", - "xdks/typescript/install", - "xdks/typescript/authentication", - "xdks/typescript/pagination", - "xdks/typescript/streaming", - { - "group": "API Reference", - "pages": [ - "xdks/typescript/reference/modules", - { - "group": "Interfaces", - "pages": [ - { - "group": "Client", - "pages": [ - "xdks/typescript/reference/interfaces/ClientConfig" - ] - }, - { - "group": "Http", - "pages": [ - "xdks/typescript/reference/interfaces/HttpClientRequestOptions", - "xdks/typescript/reference/interfaces/HttpResponse" - ] - }, - { - "group": "Misc", - "pages": [ - "xdks/typescript/reference/interfaces/ApiResponse", - "xdks/typescript/reference/interfaces/PaginatedResponse", - "xdks/typescript/reference/interfaces/PaginationMeta", - "xdks/typescript/reference/interfaces/RequestOptions", - "xdks/typescript/reference/interfaces/Schemas.ActivityStreamingResponse", - "xdks/typescript/reference/interfaces/Schemas.ActivitySubscription", - "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateRequest", - "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionFilter", - "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionGetResponse", - "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateRequest", - "xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateResponse", - "xdks/typescript/reference/interfaces/Schemas.AddOrDeleteRulesResponse", - "xdks/typescript/reference/interfaces/Schemas.AddRulesRequest", - "xdks/typescript/reference/interfaces/Schemas.AllowDownloadStatus", - "xdks/typescript/reference/interfaces/Schemas.AltText", - "xdks/typescript/reference/interfaces/Schemas.Analytics", - "xdks/typescript/reference/interfaces/Schemas.AppRulesCount", - "xdks/typescript/reference/interfaces/Schemas.AudiencePolicy", - "xdks/typescript/reference/interfaces/Schemas.BookmarkAddRequest", - "xdks/typescript/reference/interfaces/Schemas.BookmarkFolderPostsResponse", - "xdks/typescript/reference/interfaces/Schemas.BookmarkFoldersResponse", - "xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse", - "xdks/typescript/reference/interfaces/Schemas.CashtagFields", - "xdks/typescript/reference/interfaces/Schemas.ClientAppUsage", - "xdks/typescript/reference/interfaces/Schemas.Community", - "xdks/typescript/reference/interfaces/Schemas.ComplianceJob", - "xdks/typescript/reference/interfaces/Schemas.Connection", - "xdks/typescript/reference/interfaces/Schemas.ContentExpiration", - "xdks/typescript/reference/interfaces/Schemas.ContextAnnotation", - "xdks/typescript/reference/interfaces/Schemas.ContextAnnotationDomainFields", - "xdks/typescript/reference/interfaces/Schemas.ContextAnnotationEntityFields", - "xdks/typescript/reference/interfaces/Schemas.CreateAttachmentsMessageRequest", - "xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobRequest", - "xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobResponse", - "xdks/typescript/reference/interfaces/Schemas.CreateDmConversationRequest", - "xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse", - "xdks/typescript/reference/interfaces/Schemas.CreateNoteRequest", - "xdks/typescript/reference/interfaces/Schemas.CreateNoteResponse", - "xdks/typescript/reference/interfaces/Schemas.CreateTextMessageRequest", - "xdks/typescript/reference/interfaces/Schemas.DeleteDmResponse", - "xdks/typescript/reference/interfaces/Schemas.DeleteNoteResponse", - "xdks/typescript/reference/interfaces/Schemas.DeleteRulesRequest", - "xdks/typescript/reference/interfaces/Schemas.DmEvent", - "xdks/typescript/reference/interfaces/Schemas.DmMediaAttachment", - "xdks/typescript/reference/interfaces/Schemas.DomainRestrictions", - "xdks/typescript/reference/interfaces/Schemas.Engagement", - "xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveExclusive", - "xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveInclusive", - "xdks/typescript/reference/interfaces/Schemas.Error", - "xdks/typescript/reference/interfaces/Schemas.EvaluateNoteRequest", - "xdks/typescript/reference/interfaces/Schemas.EvaluateNoteResponse", - "xdks/typescript/reference/interfaces/Schemas.Expansions", - "xdks/typescript/reference/interfaces/Schemas.FilteredStreamingTweetResponse", - "xdks/typescript/reference/interfaces/Schemas.FollowActivityResponsePayload", - "xdks/typescript/reference/interfaces/Schemas.FoundMediaOrigin", - "xdks/typescript/reference/interfaces/Schemas.FullTextEntities", - "xdks/typescript/reference/interfaces/Schemas.Geo", - "xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesIdResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2CommunitiesSearchResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsIdResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2ComplianceJobsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2ConnectionsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsIdDmEventsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2DmConversationsWithParticipantIdDmEventsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2DmEventsEventIdResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2DmEventsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidContactResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidPayment_networksResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2FdxAccountsAccountidTransactionsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2FdxCustomersCurrentResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2Insights28hrResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2InsightsHistoricalResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2LikesFirehoseStreamResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2LikesSample10StreamResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2ListsIdFollowersResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2ListsIdMembersResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2ListsIdResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2ListsIdTweetsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2MediaAnalyticsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2MediaMediaKeyResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2MediaResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2NewsIdResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2NewsSearchResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchNotesWrittenResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2NotesSearchPostsEligibleForNotesResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2SpacesByCreatorIdsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdBuyersResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2SpacesIdTweetsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2SpacesResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2SpacesSearchResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TrendsByWoeidWoeidResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsAnalyticsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsAllResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsCountsRecentResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangEnResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangJaResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangKoResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamLangPtResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsFirehoseStreamResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdLikingUsersResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdQuoteTweetsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetedByResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsIdRetweetsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSample10StreamResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSampleStreamResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchAllResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchRecentResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2TweetsSearchStreamRulesCountsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsageTweetsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersByResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersByUsernameUsernameResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBlockingResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdBookmarksResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowedListsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowersResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdFollowingResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdLikedTweetsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdListMembershipsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMentionsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdMutingResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdOwnedListsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdPinnedListsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTimelinesReverseChronologicalResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersIdTweetsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersMeResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersPersonalizedTrendsResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersRepostsOfMeResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2UsersSearchResponse", - "xdks/typescript/reference/interfaces/Schemas.Get2WebhooksResponse", - "xdks/typescript/reference/interfaces/Schemas.HashtagFields", - "xdks/typescript/reference/interfaces/Schemas.KillAllConnectionsResponse", - "xdks/typescript/reference/interfaces/Schemas.LikeComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.LikeWithTweetAuthor", - "xdks/typescript/reference/interfaces/Schemas.List", - "xdks/typescript/reference/interfaces/Schemas.ListAddUserRequest", - "xdks/typescript/reference/interfaces/Schemas.ListCreateRequest", - "xdks/typescript/reference/interfaces/Schemas.ListCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.ListDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.ListFollowedRequest", - "xdks/typescript/reference/interfaces/Schemas.ListFollowedResponse", - "xdks/typescript/reference/interfaces/Schemas.ListMutateResponse", - "xdks/typescript/reference/interfaces/Schemas.ListPinnedRequest", - "xdks/typescript/reference/interfaces/Schemas.ListPinnedResponse", - "xdks/typescript/reference/interfaces/Schemas.ListUnpinResponse", - "xdks/typescript/reference/interfaces/Schemas.ListUpdateRequest", - "xdks/typescript/reference/interfaces/Schemas.ListUpdateResponse", - "xdks/typescript/reference/interfaces/Schemas.ManagementInfo", - "xdks/typescript/reference/interfaces/Schemas.Media", - "xdks/typescript/reference/interfaces/Schemas.MediaAnalytics", - "xdks/typescript/reference/interfaces/Schemas.MediaMetrics", - "xdks/typescript/reference/interfaces/Schemas.MediaTimestampedMetrics", - "xdks/typescript/reference/interfaces/Schemas.MediaUploadAppendResponse", - "xdks/typescript/reference/interfaces/Schemas.MediaUploadConfigRequest", - "xdks/typescript/reference/interfaces/Schemas.MediaUploadRequestOneShot", - "xdks/typescript/reference/interfaces/Schemas.MediaUploadResponse", - "xdks/typescript/reference/interfaces/Schemas.MentionFields", - "xdks/typescript/reference/interfaces/Schemas.MetadataCreateRequest", - "xdks/typescript/reference/interfaces/Schemas.MetadataCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.Metrics", - "xdks/typescript/reference/interfaces/Schemas.MuteUserMutationResponse", - "xdks/typescript/reference/interfaces/Schemas.MuteUserRequest", - "xdks/typescript/reference/interfaces/Schemas.News", - "xdks/typescript/reference/interfaces/Schemas.NewsActivityResponsePayload", - "xdks/typescript/reference/interfaces/Schemas.Note", - "xdks/typescript/reference/interfaces/Schemas.NoteInfo", - "xdks/typescript/reference/interfaces/Schemas.NoteTestResult", - "xdks/typescript/reference/interfaces/Schemas.PersonalizedTrend", - "xdks/typescript/reference/interfaces/Schemas.Place", - "xdks/typescript/reference/interfaces/Schemas.PlaidAccount", - "xdks/typescript/reference/interfaces/Schemas.PlaidAccountContact", - "xdks/typescript/reference/interfaces/Schemas.PlaidAccountPaymentNetwork", - "xdks/typescript/reference/interfaces/Schemas.PlaidAccountTransaction", - "xdks/typescript/reference/interfaces/Schemas.PlaidAddress", - "xdks/typescript/reference/interfaces/Schemas.PlaidCurrency", - "xdks/typescript/reference/interfaces/Schemas.PlaidCustomer", - "xdks/typescript/reference/interfaces/Schemas.PlaidName", - "xdks/typescript/reference/interfaces/Schemas.PlaidTelephone", - "xdks/typescript/reference/interfaces/Schemas.Point", - "xdks/typescript/reference/interfaces/Schemas.Poll", - "xdks/typescript/reference/interfaces/Schemas.PollOption", - "xdks/typescript/reference/interfaces/Schemas.PreviewImage", - "xdks/typescript/reference/interfaces/Schemas.Problem", - "xdks/typescript/reference/interfaces/Schemas.ProcessingInfo", - "xdks/typescript/reference/interfaces/Schemas.ProfileUpdateActivityResponsePayload", - "xdks/typescript/reference/interfaces/Schemas.ReplayJobCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.Rule", - "xdks/typescript/reference/interfaces/Schemas.RuleNoId", - "xdks/typescript/reference/interfaces/Schemas.RulesCount", - "xdks/typescript/reference/interfaces/Schemas.RulesLookupResponse", - "xdks/typescript/reference/interfaces/Schemas.RulesResponseMetadata", - "xdks/typescript/reference/interfaces/Schemas.SearchCount", - "xdks/typescript/reference/interfaces/Schemas.SensitiveMediaWarning", - "xdks/typescript/reference/interfaces/Schemas.SharedInfo", - "xdks/typescript/reference/interfaces/Schemas.Space", - "xdks/typescript/reference/interfaces/Schemas.Sticker", - "xdks/typescript/reference/interfaces/Schemas.StickerInfo", - "xdks/typescript/reference/interfaces/Schemas.StreamingLikeResponseV2", - "xdks/typescript/reference/interfaces/Schemas.StreamingTweetResponse", - "xdks/typescript/reference/interfaces/Schemas.SubscriptionsCountGetResponse", - "xdks/typescript/reference/interfaces/Schemas.SubscriptionsCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.SubscriptionsDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.SubscriptionsGetResponse", - "xdks/typescript/reference/interfaces/Schemas.SubscriptionsListGetResponse", - "xdks/typescript/reference/interfaces/Schemas.Subtitles", - "xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateRequest", - "xdks/typescript/reference/interfaces/Schemas.SubtitlesCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteRequest", - "xdks/typescript/reference/interfaces/Schemas.SubtitlesDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.TimestampedMetrics", - "xdks/typescript/reference/interfaces/Schemas.Topic", - "xdks/typescript/reference/interfaces/Schemas.Trend", - "xdks/typescript/reference/interfaces/Schemas.Tweet", - "xdks/typescript/reference/interfaces/Schemas.TweetComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.TweetCreateRequest", - "xdks/typescript/reference/interfaces/Schemas.TweetCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.TweetDeleteComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.TweetDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.TweetDropComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceObjectSchema", - "xdks/typescript/reference/interfaces/Schemas.TweetEditComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.TweetHideRequest", - "xdks/typescript/reference/interfaces/Schemas.TweetHideResponse", - "xdks/typescript/reference/interfaces/Schemas.TweetNotice", - "xdks/typescript/reference/interfaces/Schemas.TweetNoticeSchema", - "xdks/typescript/reference/interfaces/Schemas.TweetTakedownComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.TweetUndropComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.TweetUnviewable", - "xdks/typescript/reference/interfaces/Schemas.TweetUnviewableSchema", - "xdks/typescript/reference/interfaces/Schemas.TweetWithheld", - "xdks/typescript/reference/interfaces/Schemas.TweetWithheldComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UnlikeComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UploadSource", - "xdks/typescript/reference/interfaces/Schemas.UrlFields", - "xdks/typescript/reference/interfaces/Schemas.UrlImage", - "xdks/typescript/reference/interfaces/Schemas.Usage", - "xdks/typescript/reference/interfaces/Schemas.UsageFields", - "xdks/typescript/reference/interfaces/Schemas.User", - "xdks/typescript/reference/interfaces/Schemas.UserComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UserDeleteComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UserProfileModificationComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UserProfileModificationObjectSchema", - "xdks/typescript/reference/interfaces/Schemas.UserProtectComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UserScrubGeoObjectSchema", - "xdks/typescript/reference/interfaces/Schemas.UserScrubGeoSchema", - "xdks/typescript/reference/interfaces/Schemas.UserSuspendComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UserTakedownComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UserUndeleteComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UserUnprotectComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UserUnsuspendComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UserWithheld", - "xdks/typescript/reference/interfaces/Schemas.UserWithheldComplianceSchema", - "xdks/typescript/reference/interfaces/Schemas.UsersDMBlockCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.UsersDMUnBlockCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateRequest", - "xdks/typescript/reference/interfaces/Schemas.UsersFollowingCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.UsersFollowingDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateRequest", - "xdks/typescript/reference/interfaces/Schemas.UsersLikesCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.UsersLikesDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateRequest", - "xdks/typescript/reference/interfaces/Schemas.UsersRetweetsCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.UsersRetweetsDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.Variant", - "xdks/typescript/reference/interfaces/Schemas.WebhookConfig", - "xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateRequest", - "xdks/typescript/reference/interfaces/Schemas.WebhookConfigCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.WebhookConfigDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.WebhookConfigPutResponse", - "xdks/typescript/reference/interfaces/Schemas.WebhookLinksCreateResponse", - "xdks/typescript/reference/interfaces/Schemas.WebhookLinksDeleteResponse", - "xdks/typescript/reference/interfaces/Schemas.WebhookLinksGetResponse", - "xdks/typescript/reference/interfaces/Schemas.WebhookReplayCreateRequest" - ] - } - ] - }, - { - "group": "Classes", - "pages": [ - { - "group": "AccountActivity", - "pages": [ - "xdks/typescript/reference/classes/AccountActivityClient" - ] - }, - { - "group": "Activity", - "pages": [ - "xdks/typescript/reference/classes/ActivityClient" - ] - }, - { - "group": "Client", - "pages": [ - "xdks/typescript/reference/classes/Client" - ] - }, - { - "group": "Clients", - "pages": [ - "xdks/typescript/reference/classes/NewsClient" - ] - }, - { - "group": "Communities", - "pages": [ - "xdks/typescript/reference/classes/CommunitiesClient" - ] - }, - { - "group": "CommunityNotes", - "pages": [ - "xdks/typescript/reference/classes/CommunityNotesClient" - ] - }, - { - "group": "Compliance", - "pages": [ - "xdks/typescript/reference/classes/ComplianceClient" - ] - }, - { - "group": "Connections", - "pages": [ - "xdks/typescript/reference/classes/ConnectionsClient" - ] - }, - { - "group": "Core", - "pages": [ - "xdks/typescript/reference/classes/ApiError" - ] - }, - { - "group": "DirectMessages", - "pages": [ - "xdks/typescript/reference/classes/DirectMessagesClient" - ] - }, - { - "group": "General", - "pages": [ - "xdks/typescript/reference/classes/GeneralClient" - ] - }, - { - "group": "Http", - "pages": [ - "xdks/typescript/reference/classes/HttpClient" - ] - }, - { - "group": "Lists", - "pages": [ - "xdks/typescript/reference/classes/ListsClient" - ] - }, - { - "group": "Media", - "pages": [ - "xdks/typescript/reference/classes/MediaClient" - ] - }, - { - "group": "Pagination", - "pages": [ - "xdks/typescript/reference/classes/EventPaginator", - "xdks/typescript/reference/classes/PostPaginator", - "xdks/typescript/reference/classes/UserPaginator" - ] - }, - { - "group": "Paginator", - "pages": [ - "xdks/typescript/reference/classes/Paginator" - ] - }, - { - "group": "Posts", - "pages": [ - "xdks/typescript/reference/classes/PostsClient" - ] - }, - { - "group": "Spaces", - "pages": [ - "xdks/typescript/reference/classes/SpacesClient" - ] - }, - { - "group": "Stream", - "pages": [ - "xdks/typescript/reference/classes/StreamClient" - ] - }, - { - "group": "Trends", - "pages": [ - "xdks/typescript/reference/classes/TrendsClient" - ] - }, - { - "group": "Usage", - "pages": [ - "xdks/typescript/reference/classes/UsageClient" - ] - }, - { - "group": "Users", - "pages": [ - "xdks/typescript/reference/classes/UsersClient" - ] - }, - { - "group": "Webhooks", - "pages": [ - "xdks/typescript/reference/classes/WebhooksClient" - ] - } - ] - } + {"group": "AccountActivity", "pages": ["xdks/typescript/reference/classes/AccountActivityClient"]}, + {"group": "Activity", "pages": ["xdks/typescript/reference/classes/ActivityClient"]}, + {"group": "Client", "pages": ["xdks/typescript/reference/classes/Client"]}, + {"group": "Clients", "pages": ["xdks/typescript/reference/classes/NewsClient"]}, + {"group": "Communities", "pages": ["xdks/typescript/reference/classes/CommunitiesClient"]}, + {"group": "CommunityNotes", "pages": ["xdks/typescript/reference/classes/CommunityNotesClient"]}, + {"group": "Compliance", "pages": ["xdks/typescript/reference/classes/ComplianceClient"]}, + {"group": "Connections", "pages": ["xdks/typescript/reference/classes/ConnectionsClient"]}, + {"group": "Core", "pages": ["xdks/typescript/reference/classes/ApiError"]}, + {"group": "DirectMessages", "pages": ["xdks/typescript/reference/classes/DirectMessagesClient"]}, + {"group": "General", "pages": ["xdks/typescript/reference/classes/GeneralClient"]}, + {"group": "Http", "pages": ["xdks/typescript/reference/classes/HttpClient"]}, + {"group": "Lists", "pages": ["xdks/typescript/reference/classes/ListsClient"]}, + {"group": "Media", "pages": ["xdks/typescript/reference/classes/MediaClient"]}, + {"group": "Pagination", "pages": ["xdks/typescript/reference/classes/EventPaginator", "xdks/typescript/reference/classes/PostPaginator", "xdks/typescript/reference/classes/UserPaginator"]}, + {"group": "Paginator", "pages": ["xdks/typescript/reference/classes/Paginator"]}, + {"group": "Posts", "pages": ["xdks/typescript/reference/classes/PostsClient"]}, + {"group": "Spaces", "pages": ["xdks/typescript/reference/classes/SpacesClient"]}, + {"group": "Stream", "pages": ["xdks/typescript/reference/classes/StreamClient"]}, + {"group": "Trends", "pages": ["xdks/typescript/reference/classes/TrendsClient"]}, + {"group": "Usage", "pages": ["xdks/typescript/reference/classes/UsageClient"]}, + {"group": "Users", "pages": ["xdks/typescript/reference/classes/UsersClient"]}, + {"group": "Webhooks", "pages": ["xdks/typescript/reference/classes/WebhooksClient"]} ] } ] @@ -1959,21 +1209,9 @@ ], "global": { "anchors": [ - { - "anchor": "Developer Console", - "href": "https://developer.x.com/en/portal/petition/essential/basic-info", - "icon": "circle-play" - }, - { - "anchor": "Forums", - "href": "https://devcommunity.x.com", - "icon": "messages" - }, - { - "anchor": "GitHub", - "href": "https://github.com/xdevplatform", - "icon": "github" - } + {"anchor": "Developer Console", "href": "https://developer.x.com/en/portal/petition/essential/basic-info", "icon": "circle-play"}, + {"anchor": "Forums", "href": "https://devcommunity.x.com", "icon": "messages"}, + {"anchor": "GitHub", "href": "https://github.com/xdevplatform", "icon": "github"} ] } }, @@ -1992,10 +1230,7 @@ }, "navbar": { "links": [ - { - "label": "Support", - "href": "/support" - } + {"label": "Support", "href": "/support"} ], "primary": { "type": "button", @@ -2009,730 +1244,199 @@ "github": "https://github.com/xdevplatform" }, "links": [ + { + "header": "Resources", + "items": [ + {"label": "Status", "href": "/status"} + ] + }, { "header": "Legal", "items": [ - { - "label": "Terms of Service", - "href": "https://x.com/en/tos" - }, - { - "label": "Privacy Policy", - "href": "https://x.com/en/privacy" - }, - { - "label": "Cookies", - "href": "https://help.x.com/en/rules-and-policies/x-cookies" - }, - { - "label": "Developer Terms", - "href": "https://docs.x.com/developer-terms" - } + {"label": "Terms of Service", "href": "https://x.com/en/tos"}, + {"label": "Privacy Policy", "href": "https://x.com/en/privacy"}, + {"label": "Cookies", "href": "https://help.x.com/en/rules-and-policies/x-cookies"}, + {"label": "Developer Terms", "href": "https://docs.x.com/developer-terms"} ] } ] }, "redirects": [ - { - "source": "/updates/changelog", - "destination": "/changelog" - }, - { - "source": "/status/status", - "destination": "/status" - }, - { - "source": "/status/incident", - "destination": "/incidents" - }, - { - "source": "/x-api/users/personalized-trends/personalized-trends", - "destination": "/x-api/trends/get-personalized-trends" - }, - { - "source": "/x-api/users/personalized-trends", - "destination": "/x-api/trends/get-personalized-trends" - }, - { - "source": "/x-api/trends/introduction", - "destination": "/x-api/trends/trends-by-woeid/introduction" - }, - { - "source": "/x-api/media/media-metadata-create", - "destination": "/x-api/media/metadata-create" - }, - { - "source": "/x-api/media/media-subtitles-create", - "destination": "/x-api/media/subtitle-create" - }, - { - "source": "/x-api/media/media-subtitles-delete", - "destination": "/x-api/media/subtitle-delete" - }, - { - "source": "/resources/tutorials", - "destination": "/tutorials" - }, - { - "source": "/resources/tools-and-libraries", - "destination": "/tools-and-libraries" - }, - { - "source": "/platform-overview", - "destination": "/overview" - }, - { - "source": "/home", - "destination": "/overview" - }, - { - "source": "/resources/newsletter", - "destination": "/newsletter" - }, - { - "source": "/resources/api-reference-index", - "destination": "/api-reference-index" - }, - { - "source": "/resources/fundamentals/:slug*", - "destination": "/fundamentals/:slug*" - }, - { - "source": "/resources/enterprise/:slug*", - "destination": "/enterprise/:slug*" - }, - { - "source": "/x-api/account-activity/check-if-a-subscription-exists-for-a-given-webhook-and-user", - "destination": "/x-api/account-activity/validate-subscription" - }, - { - "source": "/x-api/account-activity/deactivates-a-subscription-for-the-specified-webhook-and-user-id", - "destination": "/x-api/account-activity/delete-subscription" - }, - { - "source": "/x-api/account-activity/get-a-count-of-subscriptions-that-are-currently-active-on-your-account", - "destination": "/x-api/account-activity/get-subscription-count" - }, - { - "source": "/x-api/account-activity/get-a-list-of-the-current-all-activity-type-subscriptions-for-the-specified-webhook", - "destination": "/x-api/account-activity/get-subscriptions" - }, - { - "source": "/x-api/account-activity/request-activity-replay", - "destination": "/x-api/account-activity/create-replay-job" - }, - { - "source": "/x-api/account-activity/subscribes-the-provided-application-to-all-events-for-the-provided-user-context-for-all-message-types", - "destination": "/x-api/account-activity/create-subscription" - }, - { - "source": "/x-api/bookmarks/add-post-to-bookmarks", - "destination": "/x-api/bookmarks/create-bookmark" - }, - { - "source": "/x-api/bookmarks/bookmark-folder-posts-by-user-and-folder-id", - "destination": "/x-api/bookmarks/get-bookmarks-by-folder-id" - }, - { - "source": "/x-api/bookmarks/bookmark-folders-by-user", - "destination": "/x-api/bookmarks/get-bookmark-folders" - }, - { - "source": "/x-api/bookmarks/bookmarks-by-user", - "destination": "/x-api/bookmarks/get-bookmarks" - }, - { - "source": "/x-api/bookmarks/remove-a-bookmarked-post", - "destination": "/x-api/bookmarks/delete-bookmark" - }, - { - "source": "/x-api/communities/communities-lookup-by-community-id", - "destination": "/x-api/communities/get-community-by-id" - }, - { - "source": "/x-api/compliance/get-compliance-job", - "destination": "/x-api/compliance/get-compliance-job-by-id" - }, - { - "source": "/x-api/compliance/likes-compliance-stream", - "destination": "/x-api/compliance/stream-likes-compliance-data" - }, - { - "source": "/x-api/compliance/list-compliance-jobs", - "destination": "/x-api/compliance/get-compliance-jobs" - }, - { - "source": "/x-api/compliance/posts-compliance-stream", - "destination": "/x-api/compliance/stream-posts-compliance-data" - }, - { - "source": "/x-api/compliance/users-compliance-stream", - "destination": "/x-api/compliance/stream-users-compliance-data" - }, - { - "source": "/x-api/connection/force-kills-all-streaming-connections-of-the-authenticated-application", - "destination": "/x-api/connections/terminate-all-connections" - }, - { - "source": "/x-api/direct-messages/create-a-new-dm-conversation", - "destination": "/x-api/direct-messages/create-dm-conversation" - }, - { - "source": "/x-api/direct-messages/delete-dm", - "destination": "/x-api/direct-messages/delete-dm-event" - }, - { - "source": "/x-api/direct-messages/get-dm-events-by-id", - "destination": "/x-api/direct-messages/get-dm-event-by-id" - }, - { - "source": "/x-api/direct-messages/get-recent-dm-events", - "destination": "/x-api/direct-messages/get-dm-events" - }, - { - "source": "/x-api/direct-messages/send-a-new-message-to-a-dm-conversation", - "destination": "/x-api/direct-messages/create-dm-message-by-conversation-id" - }, - { - "source": "/x-api/direct-messages/send-a-new-message-to-a-user", - "destination": "/x-api/direct-messages/create-dm-message-by-participant-id" - }, - { - "source": "/x-api/likes/likes-firehose-stream", - "destination": "/x-api/likes/stream-all-likes" - }, - { - "source": "/x-api/likes/likes-sample-10-stream", - "destination": "/x-api/likes/stream-sampled-likes" - }, - { - "source": "/x-api/lists/add-a-list-member", - "destination": "/x-api/lists/add-list-member" - }, - { - "source": "/x-api/lists/follow-a-list", - "destination": "/x-api/lists/follow-list" - }, - { - "source": "/x-api/lists/get-a-users-list-memberships", - "destination": "/x-api/lists/get-list-memberships" - }, - { - "source": "/x-api/lists/get-a-users-owned-lists", - "destination": "/x-api/lists/get-owned-lists" - }, - { - "source": "/x-api/lists/get-a-users-pinned-lists", - "destination": "/x-api/lists/get-pinned-lists" - }, - { - "source": "/x-api/lists/get-users-followed-lists", - "destination": "/x-api/lists/get-followed-lists" - }, - { - "source": "/x-api/lists/list-lookup-by-list-id", - "destination": "/x-api/lists/get-list-by-id" - }, - { - "source": "/x-api/lists/pin-a-list", - "destination": "/x-api/lists/pin-list" - }, - { - "source": "/x-api/lists/remove-a-list-member", - "destination": "/x-api/lists/remove-list-member" - }, - { - "source": "/x-api/lists/unfollow-a-list", - "destination": "/x-api/lists/unfollow-list" - }, - { - "source": "/x-api/lists/unpin-a-list", - "destination": "/x-api/lists/unpin-list" - }, - { - "source": "/x-api/media/media-lookup-by-media-key-1", - "destination": "/x-api/media/get-media-by-media-key" - }, - { - "source": "/x-api/media/media-lookup-by-media-key", - "destination": "/x-api/media/get-media-by-media-keys" - }, - { - "source": "/x-api/media/media-upload-finalize", - "destination": "/x-api/media/finalize-media-upload" - }, - { - "source": "/x-api/media/image-or-subtitle-media-upload", - "destination": "/x-api/media/upload-media" - }, - { - "source": "/x-api/media/media-upload-initialize", - "destination": "/x-api/media/initialize-media-upload" - }, - { - "source": "/x-api/media/media-upload-append", - "destination": "/x-api/media/append-media-upload" - }, - { - "source": "/x-api/media/media-upload-status", - "destination": "/x-api/media/get-media-upload-status" - }, - { - "source": "/x-api/media/metadata-create", - "destination": "/x-api/media/create-media-metadata" - }, - { - "source": "/x-api/media/subtitle-create", - "destination": "/x-api/media/create-media-subtitles" - }, - { - "source": "/x-api/media/subtitle-delete", - "destination": "/x-api/media/delete-media-subtitles" - }, - { - "source": "/x-api/openapi/returns-the-openapi-specification-document", - "destination": "/x-api/openapi/get-openapi-spec" - }, - { - "source": "/x-api/spaces/retrieve-posts-from-a-space", - "destination": "/x-api/spaces/get-space-posts" - }, - { - "source": "/x-api/spaces/retrieve-the-list-of-users-who-purchased-a-ticket-to-the-given-space", - "destination": "/x-api/spaces/get-space-ticket-buyers" - }, - { - "source": "/x-api/spaces/search-for-spaces", - "destination": "/x-api/spaces/search-spaces" - }, - { - "source": "/x-api/spaces/space-lookup-by-space-id", - "destination": "/x-api/spaces/get-space-by-id" - }, - { - "source": "/x-api/spaces/space-lookup-by-their-creators", - "destination": "/x-api/spaces/get-spaces-by-creator-ids" - }, - { - "source": "/x-api/spaces/space-lookup-up-space-ids", - "destination": "/x-api/spaces/get-spaces-by-ids" - }, - { - "source": "/x-api/trends/trends", - "destination": "/x-api/trends/get-trends-by-woeid" - }, - { - "source": "/x-api/posts/adddelete-rules", - "destination": "/x-api/posts/update-stream-rules" - }, - { - "source": "/x-api/posts/get-engagement-analytics", - "destination": "/x-api/posts/get-post-analytics" - }, - { - "source": "/x-api/posts/causes-the-user-in-the-path-to-like-the-specified-post", - "destination": "/x-api/posts/like-post" - }, - { - "source": "/x-api/posts/causes-the-user-in-the-path-to-repost-the-specified-post", - "destination": "/x-api/posts/repost-post" - }, - { - "source": "/x-api/posts/causes-the-user-in-the-path-to-unlike-the-specified-post", - "destination": "/x-api/posts/unlike-post" - }, - { - "source": "/x-api/posts/causes-the-user-in-the-path-to-unretweet-the-specified-post", - "destination": "/x-api/posts/unrepost-post" - }, - { - "source": "/x-api/posts/creation-of-a-post", - "destination": "/x-api/posts/create-post" - }, - { - "source": "/x-api/posts/english-language-firehose-stream", - "destination": "/x-api/posts/stream-english-posts" - }, - { - "source": "/x-api/posts/filtered-stream", - "destination": "/x-api/posts/stream-filtered-posts" - }, - { - "source": "/x-api/posts/firehose-stream", - "destination": "/x-api/posts/stream-all-posts" - }, - { - "source": "/x-api/posts/full-archive-search-counts", - "destination": "/x-api/posts/get-count-of-all-posts" - }, - { - "source": "/x-api/posts/full-archive-search", - "destination": "/x-api/posts/search-all-posts" - }, - { - "source": "/x-api/posts/get-historical-metrics-for-posts", - "destination": "/x-api/posts/get-historical-post-insights" - }, - { - "source": "/x-api/posts/get-last-28hr-metrics-for-posts", - "destination": "/x-api/posts/get-28-hour-post-insights" - }, - { - "source": "/x-api/posts/hide-replies", - "destination": "/x-api/posts/hide-reply" - }, - { - "source": "/x-api/posts/japanese-language-firehose-stream", - "destination": "/x-api/posts/stream-japanese-posts" - }, - { - "source": "/x-api/posts/korean-language-firehose-stream", - "destination": "/x-api/posts/stream-korean-posts" - }, - { - "source": "/x-api/posts/list-posts-timeline-by-list-id", - "destination": "/x-api/posts/get-list-posts" - }, - { - "source": "/x-api/posts/portuguese-language-firehose-stream", - "destination": "/x-api/posts/stream-portuguese-posts" - }, - { - "source": "/x-api/posts/post-delete-by-post-id", - "destination": "/x-api/posts/delete-post" - }, - { - "source": "/x-api/posts/post-lookup-by-post-id", - "destination": "/x-api/posts/get-post-by-id" - }, - { - "source": "/x-api/posts/post-lookup-by-post-ids", - "destination": "/x-api/posts/get-posts-by-ids" - }, - { - "source": "/x-api/posts/recent-search-counts", - "destination": "/x-api/posts/get-count-of-recent-posts" - }, - { - "source": "/x-api/posts/recent-search", - "destination": "/x-api/posts/search-recent-posts" - }, - { - "source": "/x-api/posts/retrieve-posts-that-quote-a-post", - "destination": "/x-api/posts/get-quoted-posts" - }, - { - "source": "/x-api/posts/retrieve-posts-that-repost-a-post", - "destination": "/x-api/posts/get-reposts" - }, - { - "source": "/x-api/posts/returns-post-objects-liked-by-the-provided-user-id", - "destination": "/x-api/posts/get-liked-posts" - }, - { - "source": "/x-api/posts/rules-lookup", - "destination": "/x-api/posts/get-stream-rules" - }, - { - "source": "/x-api/posts/sample-10-stream", - "destination": "/x-api/posts/stream-10-sampled-posts" - }, - { - "source": "/x-api/posts/sample-stream", - "destination": "/x-api/posts/stream-sampled-posts" - }, - { - "source": "/x-api/posts/user-home-timeline-by-user-id", - "destination": "/x-api/posts/get-timeline" - }, - { - "source": "/x-api/posts/user-mention-timeline-by-user-id", - "destination": "/x-api/posts/get-mentions" - }, - { - "source": "/x-api/posts/user-posts-timeline-by-user-id", - "destination": "/x-api/posts/get-posts" - }, - { - "source": "/x-api/posts/rules-count", - "destination": "/x-api/posts/get-stream-rule-counts" - }, - { - "source": "/x-api/usage/post-usage", - "destination": "/x-api/usage/get-usage" - }, - { - "source": "/x-api/users/causes-dms-tofrom-the-target-user-in-the-path-to-be-blocked-by-the-authenticated-request-user", - "destination": "/x-api/users/block-dms" - }, - { - "source": "/x-api/users/causes-dms-tofrom-the-target-user-in-the-path-to-be-unblocked-by-the-authenticated-request-user", - "destination": "/x-api/users/unblock-dms" - }, - { - "source": "/x-api/users/followers-by-user-id", - "destination": "/x-api/users/get-followers" - }, - { - "source": "/x-api/users/following-by-user-id", - "destination": "/x-api/users/get-following" - }, - { - "source": "/x-api/users/mute-user-by-user-id", - "destination": "/x-api/users/mute-user" - }, - { - "source": "/x-api/users/returns-repost-of-user", - "destination": "/x-api/users/get-reposts-of-me" - }, - { - "source": "/x-api/users/returns-user-objects-that-are-blocked-by-provided-user-id", - "destination": "/x-api/users/get-blocking" - }, - { - "source": "/x-api/users/returns-user-objects-that-are-members-of-a-list-by-the-provided-list-id", - "destination": "/x-api/users/get-list-members" - }, - { - "source": "/x-api/users/returns-user-objects-that-are-muted-by-the-provided-user-id", - "destination": "/x-api/users/get-muting" - }, - { - "source": "/x-api/users/returns-user-objects-that-follow-a-list-by-the-provided-list-id", - "destination": "/x-api/users/get-list-followers" - }, - { - "source": "/x-api/users/returns-user-objects-that-have-liked-the-provided-post-id", - "destination": "/x-api/users/get-liking-users" - }, - { - "source": "/x-api/users/returns-user-objects-that-have-retweeted-the-provided-post-id", - "destination": "/x-api/users/get-reposted-by" - }, - { - "source": "/x-api/users/unmute-user-by-user-id", - "destination": "/x-api/users/unmute-user" - }, - { - "source": "/x-api/users/user-lookup-by-id", - "destination": "/x-api/users/get-user-by-id" - }, - { - "source": "/x-api/users/user-lookup-by-ids", - "destination": "/x-api/users/get-users-by-ids" - }, - { - "source": "/x-api/users/user-lookup-by-username", - "destination": "/x-api/users/get-user-by-username" - }, - { - "source": "/x-api/users/user-lookup-by-usernames", - "destination": "/x-api/users/get-users-by-usernames" - }, - { - "source": "/x-api/users/user-lookup-me", - "destination": "/x-api/users/get-my-user" - }, - { - "source": "/x-api/users/user-search", - "destination": "/x-api/users/search-users" - }, - { - "source": "/x-api/webhooks/create-webhook-config", - "destination": "/x-api/webhooks/create-webhook" - }, - { - "source": "/x-api/webhooks/delete-webhook-config", - "destination": "/x-api/webhooks/delete-webhook" - }, - { - "source": "/x-api/webhooks/get-a-list-of-webhook-configs-associated-with-a-client-app", - "destination": "/x-api/webhooks/get-webhook" - }, - { - "source": "/x-api/webhooks/webhook-crc-check", - "destination": "/x-api/webhooks/validate-webhook" - }, - { - "source": "/x-api/posts/get-posts", - "destination": "/x-api/users/get-posts" - }, - { - "source": "/x-api/posts/get-mentions", - "destination": "/x-api/users/get-mentions" - }, - { - "source": "/x-api/posts/get-timeline", - "destination": "/x-api/users/get-timeline" - }, - { - "source": "/x-api/bookmarks/get-bookmark-folders", - "destination": "/x-api/users/get-bookmark-folders" - }, - { - "source": "/x-api/bookmarks/get-bookmarks-by-folder-id", - "destination": "/x-api/users/get-bookmarks-by-folder-id" - }, - { - "source": "/x-api/bookmarks/get-bookmarks", - "destination": "/x-api/users/get-bookmarks" - }, - { - "source": "/x-api/bookmarks/create-bookmark", - "destination": "/x-api/users/create-bookmark" - }, - { - "source": "/x-api/bookmarks/delete-bookmark", - "destination": "/x-api/users/delete-bookmark" - }, - { - "source": "/x-api/users/get-reposted-by", - "destination": "/x-api/posts/get-reposted-by" - }, - { - "source": "/x-api/posts/repost-post", - "destination": "/x-api/users/repost-post" - }, - { - "source": "/x-api/posts/unrepost-post", - "destination": "/x-api/users/unrepost-post" - }, - { - "source": "/x-api/posts/get-liked-posts", - "destination": "/x-api/users/get-liked-posts" - }, - { - "source": "/x-api/users/get-liking-users", - "destination": "/x-api/posts/get-liking-users" - }, - { - "source": "/x-api/posts/like-post", - "destination": "/x-api/users/like-post" - }, - { - "source": "/x-api/posts/unlike-post", - "destination": "/x-api/users/unlike-post" - }, - { - "source": "/x-api/lists/get-followed-lists", - "destination": "/x-api/users/get-followed-lists" - }, - { - "source": "/x-api/lists/get-owned-lists", - "destination": "/x-api/users/get-owned-lists" - }, - { - "source": "/x-api/posts/get-list-posts", - "destination": "/x-api/lists/get-list-posts" - }, - { - "source": "/x-api/lists/follow-list", - "destination": "/x-api/users/follow-list" - }, - { - "source": "/x-api/lists/unfollow-list", - "destination": "/x-api/users/unfollow-list" - }, - { - "source": "/x-api/lists/get-list-memberships", - "destination": "/x-api/users/get-list-memberships" - }, - { - "source": "/x-api/users/get-list-followers", - "destination": "/x-api/lists/get-list-followers" - }, - { - "source": "/x-api/users/get-list-members", - "destination": "/x-api/lists/get-list-members" - }, - { - "source": "/x-api/lists/get-pinned-lists", - "destination": "/x-api/users/get-pinned-lists" - }, - { - "source": "/x-api/lists/pin-list", - "destination": "/x-api/users/pin-list" - }, - { - "source": "/x-api/lists/unpin-list", - "destination": "/x-api/users/unpin-list" - }, - { - "source": "/enterprise/forms/enterprise-api-interest", - "destination": "/forms/enterprise-api-interest" - }, - { - "source": "/enterprise/forms/government-end-user-request", - "destination": "/forms/government-end-user-request" - }, - { - "source": "/enterprise/forms/survey", - "destination": "/forms/survey" - }, - { - "source": "/enterprise/forms/application-trial", - "destination": "/forms/application-trial" - }, - { - "source": "/enterprise/forms/use-case/initial", - "destination": "/forms/use-case/initial" - }, - { - "source": "/enterprise/forms/use-case/modification", - "destination": "/forms/use-case/modification" - }, - { - "source": "/enterprise/forms/use-case/public-sector", - "destination": "/forms/use-case/public-sector" - }, - { - "source": "/enterprise/forms/use-case/upgrade", - "destination": "/forms/use-case/upgrade" - }, - { - "source": "/developer-terms/more-on-restricted-use-cases", - "destination": "/developer-terms/restricted-use-cases" - }, - { - "source": "/incidents", - "destination": "/status" - }, - { - "source": "/x-api/tools-and-libraries", - "destination": "/tools-and-libraries" - }, - { - "source": "/x-api/tools-and-libraries/overview", - "destination": "/tools-and-libraries" - }, - { - "source": "/x-api/tools-and-libraries/sdks", - "destination": "/tools-and-libraries" - }, - { - "source": "/enterprise-api/tools-and-libraries", - "destination": "/tools-and-libraries" - }, - { - "source": "/xdks/overview", - "destination": "/tools-and-libraries" - }, - { - "source": "/x-api/what-to-build", - "destination": "/what-to-build" - }, - { - "source": "/x-api/getting-started/make-your-first-request", - "destination": "/make-your-first-request" - }, - { - "source": "/x-api/getting-started/important-resources", - "destination": "/important-resources" - }, - { - "source": "/developer-terms/agreement-and-policy", - "destination": "/developer-terms/policy" - } + {"source": "/updates/changelog", "destination": "/changelog"}, + {"source": "/status/status", "destination": "/status"}, + {"source": "/status/incident", "destination": "/incidents"}, + {"source": "/x-api/users/personalized-trends/personalized-trends", "destination": "/x-api/trends/get-personalized-trends"}, + {"source": "/x-api/users/personalized-trends", "destination": "/x-api/trends/get-personalized-trends"}, + {"source": "/x-api/trends/introduction", "destination": "/x-api/trends/trends-by-woeid/introduction"}, + {"source": "/x-api/media/media-metadata-create", "destination": "/x-api/media/metadata-create"}, + {"source": "/x-api/media/media-subtitles-create", "destination": "/x-api/media/subtitle-create"}, + {"source": "/x-api/media/media-subtitles-delete", "destination": "/x-api/media/subtitle-delete"}, + {"source": "/resources/tutorials", "destination": "/tutorials"}, + {"source": "/resources/tools-and-libraries", "destination": "/tools-and-libraries"}, + {"source": "/platform-overview", "destination": "/overview"}, + {"source": "/home", "destination": "/overview"}, + {"source": "/resources/newsletter", "destination": "/newsletter"}, + {"source": "/resources/api-reference-index", "destination": "/api-reference-index"}, + {"source": "/resources/fundamentals/:slug*", "destination": "/fundamentals/:slug*"}, + {"source": "/resources/enterprise/:slug*", "destination": "/enterprise/:slug*"}, + {"source": "/x-api/account-activity/check-if-a-subscription-exists-for-a-given-webhook-and-user", "destination": "/x-api/account-activity/validate-subscription"}, + {"source": "/x-api/account-activity/deactivates-a-subscription-for-the-specified-webhook-and-user-id", "destination": "/x-api/account-activity/delete-subscription"}, + {"source": "/x-api/account-activity/get-a-count-of-subscriptions-that-are-currently-active-on-your-account", "destination": "/x-api/account-activity/get-subscription-count"}, + {"source": "/x-api/account-activity/get-a-list-of-the-current-all-activity-type-subscriptions-for-the-specified-webhook", "destination": "/x-api/account-activity/get-subscriptions"}, + {"source": "/x-api/account-activity/request-activity-replay", "destination": "/x-api/account-activity/create-replay-job"}, + {"source": "/x-api/account-activity/subscribes-the-provided-application-to-all-events-for-the-provided-user-context-for-all-message-types", "destination": "/x-api/account-activity/create-subscription"}, + {"source": "/x-api/bookmarks/add-post-to-bookmarks", "destination": "/x-api/bookmarks/create-bookmark"}, + {"source": "/x-api/bookmarks/bookmark-folder-posts-by-user-and-folder-id", "destination": "/x-api/bookmarks/get-bookmarks-by-folder-id"}, + {"source": "/x-api/bookmarks/bookmark-folders-by-user", "destination": "/x-api/bookmarks/get-bookmark-folders"}, + {"source": "/x-api/bookmarks/bookmarks-by-user", "destination": "/x-api/bookmarks/get-bookmarks"}, + {"source": "/x-api/bookmarks/remove-a-bookmarked-post", "destination": "/x-api/bookmarks/delete-bookmark"}, + {"source": "/x-api/communities/communities-lookup-by-community-id", "destination": "/x-api/communities/get-community-by-id"}, + {"source": "/x-api/compliance/get-compliance-job", "destination": "/x-api/compliance/get-compliance-job-by-id"}, + {"source": "/x-api/compliance/likes-compliance-stream", "destination": "/x-api/compliance/stream-likes-compliance-data"}, + {"source": "/x-api/compliance/list-compliance-jobs", "destination": "/x-api/compliance/get-compliance-jobs"}, + {"source": "/x-api/compliance/posts-compliance-stream", "destination": "/x-api/compliance/stream-posts-compliance-data"}, + {"source": "/x-api/compliance/users-compliance-stream", "destination": "/x-api/compliance/stream-users-compliance-data"}, + {"source": "/x-api/connection/force-kills-all-streaming-connections-of-the-authenticated-application", "destination": "/x-api/connections/terminate-all-connections"}, + {"source": "/x-api/direct-messages/create-a-new-dm-conversation", "destination": "/x-api/direct-messages/create-dm-conversation"}, + {"source": "/x-api/direct-messages/delete-dm", "destination": "/x-api/direct-messages/delete-dm-event"}, + {"source": "/x-api/direct-messages/get-dm-events-by-id", "destination": "/x-api/direct-messages/get-dm-event-by-id"}, + {"source": "/x-api/direct-messages/get-recent-dm-events", "destination": "/x-api/direct-messages/get-dm-events"}, + {"source": "/x-api/direct-messages/send-a-new-message-to-a-dm-conversation", "destination": "/x-api/direct-messages/create-dm-message-by-conversation-id"}, + {"source": "/x-api/direct-messages/send-a-new-message-to-a-user", "destination": "/x-api/direct-messages/create-dm-message-by-participant-id"}, + {"source": "/x-api/likes/likes-firehose-stream", "destination": "/x-api/likes/stream-all-likes"}, + {"source": "/x-api/likes/likes-sample-10-stream", "destination": "/x-api/likes/stream-sampled-likes"}, + {"source": "/x-api/lists/add-a-list-member", "destination": "/x-api/lists/add-list-member"}, + {"source": "/x-api/lists/follow-a-list", "destination": "/x-api/lists/follow-list"}, + {"source": "/x-api/lists/get-a-users-list-memberships", "destination": "/x-api/lists/get-list-memberships"}, + {"source": "/x-api/lists/get-a-users-owned-lists", "destination": "/x-api/lists/get-owned-lists"}, + {"source": "/x-api/lists/get-a-users-pinned-lists", "destination": "/x-api/lists/get-pinned-lists"}, + {"source": "/x-api/lists/get-users-followed-lists", "destination": "/x-api/lists/get-followed-lists"}, + {"source": "/x-api/lists/list-lookup-by-list-id", "destination": "/x-api/lists/get-list-by-id"}, + {"source": "/x-api/lists/pin-a-list", "destination": "/x-api/lists/pin-list"}, + {"source": "/x-api/lists/remove-a-list-member", "destination": "/x-api/lists/remove-list-member"}, + {"source": "/x-api/lists/unfollow-a-list", "destination": "/x-api/lists/unfollow-list"}, + {"source": "/x-api/lists/unpin-a-list", "destination": "/x-api/lists/unpin-list"}, + {"source": "/x-api/media/media-lookup-by-media-key-1", "destination": "/x-api/media/get-media-by-media-key"}, + {"source": "/x-api/media/media-lookup-by-media-key", "destination": "/x-api/media/get-media-by-media-keys"}, + {"source": "/x-api/media/media-upload-finalize", "destination": "/x-api/media/finalize-media-upload"}, + {"source": "/x-api/media/image-or-subtitle-media-upload", "destination": "/x-api/media/upload-media"}, + {"source": "/x-api/media/media-upload-initialize", "destination": "/x-api/media/initialize-media-upload"}, + {"source": "/x-api/media/media-upload-append", "destination": "/x-api/media/append-media-upload"}, + {"source": "/x-api/media/media-upload-status", "destination": "/x-api/media/get-media-upload-status"}, + {"source": "/x-api/media/metadata-create", "destination": "/x-api/media/create-media-metadata"}, + {"source": "/x-api/media/subtitle-create", "destination": "/x-api/media/create-media-subtitles"}, + {"source": "/x-api/media/subtitle-delete", "destination": "/x-api/media/delete-media-subtitles"}, + {"source": "/x-api/openapi/returns-the-openapi-specification-document", "destination": "/x-api/openapi/get-openapi-spec"}, + {"source": "/x-api/spaces/retrieve-posts-from-a-space", "destination": "/x-api/spaces/get-space-posts"}, + {"source": "/x-api/spaces/retrieve-the-list-of-users-who-purchased-a-ticket-to-the-given-space", "destination": "/x-api/spaces/get-space-ticket-buyers"}, + {"source": "/x-api/spaces/search-for-spaces", "destination": "/x-api/spaces/search-spaces"}, + {"source": "/x-api/spaces/space-lookup-by-space-id", "destination": "/x-api/spaces/get-space-by-id"}, + {"source": "/x-api/spaces/space-lookup-by-their-creators", "destination": "/x-api/spaces/get-spaces-by-creator-ids"}, + {"source": "/x-api/spaces/space-lookup-up-space-ids", "destination": "/x-api/spaces/get-spaces-by-ids"}, + {"source": "/x-api/trends/trends", "destination": "/x-api/trends/get-trends-by-woeid"}, + {"source": "/x-api/posts/adddelete-rules", "destination": "/x-api/posts/update-stream-rules"}, + {"source": "/x-api/posts/get-engagement-analytics", "destination": "/x-api/posts/get-post-analytics"}, + {"source": "/x-api/posts/causes-the-user-in-the-path-to-like-the-specified-post", "destination": "/x-api/posts/like-post"}, + {"source": "/x-api/posts/causes-the-user-in-the-path-to-repost-the-specified-post", "destination": "/x-api/posts/repost-post"}, + {"source": "/x-api/posts/causes-the-user-in-the-path-to-unlike-the-specified-post", "destination": "/x-api/posts/unlike-post"}, + {"source": "/x-api/posts/causes-the-user-in-the-path-to-unretweet-the-specified-post", "destination": "/x-api/posts/unrepost-post"}, + {"source": "/x-api/posts/creation-of-a-post", "destination": "/x-api/posts/create-post"}, + {"source": "/x-api/posts/english-language-firehose-stream", "destination": "/x-api/posts/stream-english-posts"}, + {"source": "/x-api/posts/filtered-stream", "destination": "/x-api/posts/stream-filtered-posts"}, + {"source": "/x-api/posts/firehose-stream", "destination": "/x-api/posts/stream-all-posts"}, + {"source": "/x-api/posts/full-archive-search-counts", "destination": "/x-api/posts/get-count-of-all-posts"}, + {"source": "/x-api/posts/full-archive-search", "destination": "/x-api/posts/search-all-posts"}, + {"source": "/x-api/posts/get-historical-metrics-for-posts", "destination": "/x-api/posts/get-historical-post-insights"}, + {"source": "/x-api/posts/get-last-28hr-metrics-for-posts", "destination": "/x-api/posts/get-28-hour-post-insights"}, + {"source": "/x-api/posts/hide-replies", "destination": "/x-api/posts/hide-reply"}, + {"source": "/x-api/posts/japanese-language-firehose-stream", "destination": "/x-api/posts/stream-japanese-posts"}, + {"source": "/x-api/posts/korean-language-firehose-stream", "destination": "/x-api/posts/stream-korean-posts"}, + {"source": "/x-api/posts/list-posts-timeline-by-list-id", "destination": "/x-api/posts/get-list-posts"}, + {"source": "/x-api/posts/portuguese-language-firehose-stream", "destination": "/x-api/posts/stream-portuguese-posts"}, + {"source": "/x-api/posts/post-delete-by-post-id", "destination": "/x-api/posts/delete-post"}, + {"source": "/x-api/posts/post-lookup-by-post-id", "destination": "/x-api/posts/get-post-by-id"}, + {"source": "/x-api/posts/post-lookup-by-post-ids", "destination": "/x-api/posts/get-posts-by-ids"}, + {"source": "/x-api/posts/recent-search-counts", "destination": "/x-api/posts/get-count-of-recent-posts"}, + {"source": "/x-api/posts/recent-search", "destination": "/x-api/posts/search-recent-posts"}, + {"source": "/x-api/posts/retrieve-posts-that-quote-a-post", "destination": "/x-api/posts/get-quoted-posts"}, + {"source": "/x-api/posts/retrieve-posts-that-repost-a-post", "destination": "/x-api/posts/get-reposts"}, + {"source": "/x-api/posts/returns-post-objects-liked-by-the-provided-user-id", "destination": "/x-api/posts/get-liked-posts"}, + {"source": "/x-api/posts/rules-lookup", "destination": "/x-api/posts/get-stream-rules"}, + {"source": "/x-api/posts/sample-10-stream", "destination": "/x-api/posts/stream-10-sampled-posts"}, + {"source": "/x-api/posts/sample-stream", "destination": "/x-api/posts/stream-sampled-posts"}, + {"source": "/x-api/posts/user-home-timeline-by-user-id", "destination": "/x-api/posts/get-timeline"}, + {"source": "/x-api/posts/user-mention-timeline-by-user-id", "destination": "/x-api/posts/get-mentions"}, + {"source": "/x-api/posts/user-posts-timeline-by-user-id", "destination": "/x-api/posts/get-posts"}, + {"source": "/x-api/posts/rules-count", "destination": "/x-api/posts/get-stream-rule-counts"}, + {"source": "/x-api/usage/post-usage", "destination": "/x-api/usage/get-usage"}, + {"source": "/x-api/users/causes-dms-tofrom-the-target-user-in-the-path-to-be-blocked-by-the-authenticated-request-user", "destination": "/x-api/users/block-dms"}, + {"source": "/x-api/users/causes-dms-tofrom-the-target-user-in-the-path-to-be-unblocked-by-the-authenticated-request-user", "destination": "/x-api/users/unblock-dms"}, + {"source": "/x-api/users/followers-by-user-id", "destination": "/x-api/users/get-followers"}, + {"source": "/x-api/users/following-by-user-id", "destination": "/x-api/users/get-following"}, + {"source": "/x-api/users/mute-user-by-user-id", "destination": "/x-api/users/mute-user"}, + {"source": "/x-api/users/returns-repost-of-user", "destination": "/x-api/users/get-reposts-of-me"}, + {"source": "/x-api/users/returns-user-objects-that-are-blocked-by-provided-user-id", "destination": "/x-api/users/get-blocking"}, + {"source": "/x-api/users/returns-user-objects-that-are-members-of-a-list-by-the-provided-list-id", "destination": "/x-api/users/get-list-members"}, + {"source": "/x-api/users/returns-user-objects-that-are-muted-by-the-provided-user-id", "destination": "/x-api/users/get-muting"}, + {"source": "/x-api/users/returns-user-objects-that-follow-a-list-by-the-provided-list-id", "destination": "/x-api/users/get-list-followers"}, + {"source": "/x-api/users/returns-user-objects-that-have-liked-the-provided-post-id", "destination": "/x-api/users/get-liking-users"}, + {"source": "/x-api/users/returns-user-objects-that-have-retweeted-the-provided-post-id", "destination": "/x-api/users/get-reposted-by"}, + {"source": "/x-api/users/unmute-user-by-user-id", "destination": "/x-api/users/unmute-user"}, + {"source": "/x-api/users/user-lookup-by-id", "destination": "/x-api/users/get-user-by-id"}, + {"source": "/x-api/users/user-lookup-by-ids", "destination": "/x-api/users/get-users-by-ids"}, + {"source": "/x-api/users/user-lookup-by-username", "destination": "/x-api/users/get-user-by-username"}, + {"source": "/x-api/users/user-lookup-by-usernames", "destination": "/x-api/users/get-users-by-usernames"}, + {"source": "/x-api/users/user-lookup-me", "destination": "/x-api/users/get-my-user"}, + {"source": "/x-api/users/user-search", "destination": "/x-api/users/search-users"}, + {"source": "/x-api/webhooks/create-webhook-config", "destination": "/x-api/webhooks/create-webhook"}, + {"source": "/x-api/webhooks/delete-webhook-config", "destination": "/x-api/webhooks/delete-webhook"}, + {"source": "/x-api/webhooks/get-a-list-of-webhook-configs-associated-with-a-client-app", "destination": "/x-api/webhooks/get-webhook"}, + {"source": "/x-api/webhooks/webhook-crc-check", "destination": "/x-api/webhooks/validate-webhook"}, + {"source": "/x-api/posts/get-posts", "destination": "/x-api/users/get-posts"}, + {"source": "/x-api/posts/get-mentions", "destination": "/x-api/users/get-mentions"}, + {"source": "/x-api/posts/get-timeline", "destination": "/x-api/users/get-timeline"}, + {"source": "/x-api/bookmarks/get-bookmark-folders", "destination": "/x-api/users/get-bookmark-folders"}, + {"source": "/x-api/bookmarks/get-bookmarks-by-folder-id", "destination": "/x-api/users/get-bookmarks-by-folder-id"}, + {"source": "/x-api/bookmarks/get-bookmarks", "destination": "/x-api/users/get-bookmarks"}, + {"source": "/x-api/bookmarks/create-bookmark", "destination": "/x-api/users/create-bookmark"}, + {"source": "/x-api/bookmarks/delete-bookmark", "destination": "/x-api/users/delete-bookmark"}, + {"source": "/x-api/users/get-reposted-by", "destination": "/x-api/posts/get-reposted-by"}, + {"source": "/x-api/posts/repost-post", "destination": "/x-api/users/repost-post"}, + {"source": "/x-api/posts/unrepost-post", "destination": "/x-api/users/unrepost-post"}, + {"source": "/x-api/posts/get-liked-posts", "destination": "/x-api/users/get-liked-posts"}, + {"source": "/x-api/users/get-liking-users", "destination": "/x-api/posts/get-liking-users"}, + {"source": "/x-api/posts/like-post", "destination": "/x-api/users/like-post"}, + {"source": "/x-api/posts/unlike-post", "destination": "/x-api/users/unlike-post"}, + {"source": "/x-api/lists/get-followed-lists", "destination": "/x-api/users/get-followed-lists"}, + {"source": "/x-api/lists/get-owned-lists", "destination": "/x-api/users/get-owned-lists"}, + {"source": "/x-api/posts/get-list-posts", "destination": "/x-api/lists/get-list-posts"}, + {"source": "/x-api/lists/follow-list", "destination": "/x-api/users/follow-list"}, + {"source": "/x-api/lists/unfollow-list", "destination": "/x-api/users/unfollow-list"}, + {"source": "/x-api/lists/get-list-memberships", "destination": "/x-api/users/get-list-memberships"}, + {"source": "/x-api/users/get-list-followers", "destination": "/x-api/lists/get-list-followers"}, + {"source": "/x-api/users/get-list-members", "destination": "/x-api/lists/get-list-members"}, + {"source": "/x-api/lists/get-pinned-lists", "destination": "/x-api/users/get-pinned-lists"}, + {"source": "/x-api/lists/pin-list", "destination": "/x-api/users/pin-list"}, + {"source": "/x-api/lists/unpin-list", "destination": "/x-api/users/unpin-list"}, + {"source": "/enterprise/forms/enterprise-api-interest", "destination": "/forms/enterprise-api-interest"}, + {"source": "/enterprise/forms/government-end-user-request", "destination": "/forms/government-end-user-request"}, + {"source": "/enterprise/forms/survey", "destination": "/forms/survey"}, + {"source": "/enterprise/forms/application-trial", "destination": "/forms/application-trial"}, + {"source": "/enterprise/forms/use-case/initial", "destination": "/forms/use-case/initial"}, + {"source": "/enterprise/forms/use-case/modification", "destination": "/forms/use-case/modification"}, + {"source": "/enterprise/forms/use-case/public-sector", "destination": "/forms/use-case/public-sector"}, + {"source": "/enterprise/forms/use-case/upgrade", "destination": "/forms/use-case/upgrade"}, + {"source": "/developer-terms/more-on-restricted-use-cases", "destination": "/developer-terms/restricted-use-cases"}, + {"source": "/incidents", "destination": "/status"}, + {"source": "/x-api/tools-and-libraries", "destination": "/tools-and-libraries"}, + {"source": "/x-api/tools-and-libraries/overview", "destination": "/tools-and-libraries"}, + {"source": "/x-api/tools-and-libraries/sdks", "destination": "/tools-and-libraries"}, + {"source": "/enterprise-api/tools-and-libraries", "destination": "/tools-and-libraries"}, + {"source": "/xdks/overview", "destination": "/tools-and-libraries"}, + {"source": "/x-api/what-to-build", "destination": "/what-to-build"}, + {"source": "/x-api/getting-started/make-your-first-request", "destination": "/make-your-first-request"}, + {"source": "/x-api/getting-started/important-resources", "destination": "/important-resources"}, + {"source": "/developer-terms/agreement-and-policy", "destination": "/developer-terms/policy"} ], "seo": { "metatags": { diff --git a/style.css b/style.css index 88745ff01..69f768b46 100644 --- a/style.css +++ b/style.css @@ -106,10 +106,6 @@ td[data-label="Free Limit"] strong { left: 0 !important; } -#sidebar-content { - padding-left: 2rem; -} - #injected-slider { max-width: 400px; } @@ -171,3 +167,19 @@ td[data-label="Free Limit"] strong { .group\/card .flex { align-items: center; } + +/* Sidebar text: muted by default, brightens to white on hover. + Children (spans, svg chevrons) inherit so labels and icons track together. */ +#sidebar-content a, +#sidebar-content button, +#sidebar-content a *, +#sidebar-content button * { + color: #B0B0B0 !important; + transition: color 120ms ease; +} +#sidebar-content a:hover, +#sidebar-content a:hover *, +#sidebar-content button:hover, +#sidebar-content button:hover * { + color: #FFFFFF !important; +} From f54b4ea1f38c18e0c35fbd2640139d9bef48a540 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Mon, 4 May 2026 20:08:32 -0700 Subject: [PATCH 30/38] docs: Major agent-readiness and Mintlify scorer improvements - Comprehensive llms.txt system: root index + high-quality nested indexes (x-api/, enterprise-api/, x-ads-api/, xdks/python + typescript) - New AGENTS.md and AGENT.md with explicit guidance for AI agents, Cursor, Grok, Claude, Windsurf, etc. - Split 357k Campaign Management monolith into focused 80k Overview + dedicated API Reference page (plus navigation + link fixes) - Added rich, accurate description: frontmatter to 500+ pages (huge improvement to llms.txt usefulness and scorer Freshness/Parity) - Fixed 70+ frontmatter parsing errors (mostly migrate/integrate guides) so mintlify dev runs cleanly again - Removed duplicate legacy GNIP/enterprise content under enterprise-api/ (exact copies of x-api/ versions) - Numerous CodeGroup, Tab, self-closing tag, and link repairs for parser compatibility and agent parsing These changes directly address the Mintlify AFDocs agent scorer issues (LLMS TXT Valid/Size/Freshness, Markdown Content Parity, Page Size) and make docs.x.com dramatically more reliable and effective for LLMs and autonomous agents. --- .well-known/llms.txt | 37 + AGENT.md | 74 + AGENTS.md | 74 + docs.json | 3 +- .../account-activity/create-replay-job.mdx | 3 +- .../account-activity/create-subscription.mdx | 3 +- .../account-activity/delete-subscription.mdx | 3 +- .../get-subscription-count.mdx | 3 +- .../account-activity/get-subscriptions.mdx | 3 +- .../account-activity/migrate/overview.mdx | 2 +- .../validate-subscription.mdx | 3 +- enterprise-api/activity/activity-stream.mdx | 3 +- .../create-x-activity-subscription.mdx | 3 +- .../deletes-x-activity-subscription.mdx | 3 +- .../activity/get-x-activity-subscriptions.mdx | 3 +- enterprise-api/activity/introduction.mdx | 3 +- .../update-x-activity-subscription.mdx | 3 +- enterprise-api/bookmarks/create-bookmark.mdx | 3 +- enterprise-api/bookmarks/delete-bookmark.mdx | 3 +- .../bookmarks/get-bookmark-folders.mdx | 3 +- .../bookmarks/get-bookmarks-by-folder-id.mdx | 3 +- enterprise-api/bookmarks/get-bookmarks.mdx | 3 +- ...d-members-to-a-chat-group-conversation.mdx | 3 +- enterprise-api/chat/add-public-key.mdx | 3 +- .../chat/append-chat-media-upload.mdx | 3 +- .../chat/create-chat-group-conversation.mdx | 3 +- enterprise-api/chat/download-chat-media.mdx | 3 +- .../chat/finalize-chat-media-upload.mdx | 3 +- enterprise-api/chat/get-chat-conversation.mdx | 3 +- .../chat/get-chat-conversations.mdx | 3 +- enterprise-api/chat/get-user-public-keys.mdx | 3 +- enterprise-api/chat/initialize-chat-group.mdx | 3 +- .../chat/initialize-chat-media-upload.mdx | 3 +- .../chat/initialize-conversation-keys.mdx | 3 +- .../chat/mark-conversation-as-read.mdx | 3 +- enterprise-api/chat/send-chat-message.mdx | 3 +- enterprise-api/chat/send-typing-indicator.mdx | 3 +- .../communities/get-community-by-id.mdx | 3 +- .../communities/search-communities.mdx | 3 +- .../create-a-community-note.mdx | 3 +- .../delete-a-community-note.mdx | 3 +- .../evaluate-a-community-note.mdx | 3 +- .../community-notes/introduction.mdx | 3 +- .../search-for-community-notes-written.mdx | 3 +- ...for-posts-eligible-for-community-notes.mdx | 3 +- .../compliance/batch-compliance/integrate.mdx | 200 +- .../compliance/create-compliance-job.mdx | 3 +- .../compliance/get-compliance-job-by-id.mdx | 3 +- .../compliance/get-compliance-jobs.mdx | 3 +- .../connections/get-connection-history.mdx | 3 +- .../connections/terminate-all-connections.mdx | 3 +- .../terminate-connections-by-endpoint.mdx | 3 +- .../terminate-multiple-connections.mdx | 3 +- .../direct-messages/blocks/introduction.mdx | 131 +- .../create-dm-conversation.mdx | 3 +- .../create-dm-message-by-conversation-id.mdx | 3 +- .../create-dm-message-by-participant-id.mdx | 3 +- .../direct-messages/delete-dm-event.mdx | 3 +- .../direct-messages/download-dm-media.mdx | 3 +- .../direct-messages/get-dm-event-by-id.mdx | 3 +- .../get-dm-events-for-a-dm-conversation-1.mdx | 3 +- .../get-dm-events-for-a-dm-conversation.mdx | 3 +- .../direct-messages/get-dm-events.mdx | 3 +- .../direct-messages/lookup/integrate.mdx | 1 - .../direct-messages/lookup/migrate.mdx | 3 +- .../direct-messages/manage/integrate.mdx | 1 - .../direct-messages/manage/migrate.mdx | 3 +- .../enterprise-gnip-2.0/enterprise-gnip.mdx | 57 - .../fundamentals/account-activity.mdx | 2114 ------ .../fundamentals/data-dictionary.mdx | 4999 ------------- .../fundamentals/data-enrichments.mdx | 279 - .../fundamentals/decahose-api.mdx | 395 - .../fundamentals/edit-tweets.mdx | 110 - .../fundamentals/engagement-api.mdx | 816 --- .../fundamentals/firehouse.mdx | 382 - .../fundamentals/overview.mdx | 136 - .../fundamentals/rate-limits.mdx | 41 - .../fundamentals/rules-filtering.mdx | 340 - .../fundamentals/search-api.mdx | 1465 ---- .../fundamentals/usage.mdx | 757 -- .../enterprise-gnip-2.0/powertrack-api.mdx | 1982 ----- enterprise-api/fundamentals/consistency.mdx | 184 - .../fundamentals/consuming-streaming-data.mdx | 187 - .../fundamentals/conversation-id.mdx | 188 - .../fundamentals/data-dictionary.mdx | 2739 ------- enterprise-api/fundamentals/edit-posts.mdx | 206 - enterprise-api/fundamentals/expansions.mdx | 226 - enterprise-api/fundamentals/fields.mdx | 200 - .../fundamentals/handling-disconnections.mdx | 160 - .../fundamentals/high-volume-capacity.mdx | 148 - enterprise-api/fundamentals/metrics.mdx | 230 - enterprise-api/fundamentals/pagination.mdx | 197 - .../fundamentals/post-annotations.mdx | 229 - enterprise-api/fundamentals/post-cap.mdx | 147 - enterprise-api/fundamentals/rate-limits.mdx | 490 -- .../fundamentals/recovery-and-redundancy.mdx | 182 - .../response-codes-and-errors.mdx | 223 - enterprise-api/fundamentals/versioning.mdx | 149 - enterprise-api/general/get-openapi-spec.mdx | 3 +- enterprise-api/lists/add-list-member.mdx | 4 +- enterprise-api/lists/create-list.mdx | 4 +- enterprise-api/lists/delete-list.mdx | 4 +- enterprise-api/lists/get-list-by-id.mdx | 4 +- enterprise-api/lists/get-list-followers.mdx | 4 +- enterprise-api/lists/get-list-members.mdx | 4 +- enterprise-api/lists/get-list-posts.mdx | 4 +- .../lists/list-lookup/integrate.mdx | 1 - .../lists/list-lookup/migrate/overview.mdx | 1 + .../migrate/standard-to-twitter-api-v2.mdx | 1 + .../lists/list-members/integrate.mdx | 2 - ...bers-lookup-standard-to-twitter-api-v2.mdx | 1 + ...ist-members-standard-to-twitter-api-v2.mdx | 131 +- .../lists/list-members/migrate/overview.mdx | 1 + .../lists/list-tweets/integrate.mdx | 4 +- .../lists/list-tweets/migrate/overview.mdx | 1 + .../migrate/standard-to-twitter-api-v2.mdx | 1 + .../lists/manage-lists/integrate.mdx | 5 +- .../lists/manage-lists/migrate/overview.mdx | 1 + .../migrate/standard-to-twitter-api-v2.mdx | 438 +- .../lists/pinned-lists/integrate.mdx | 4 +- enterprise-api/lists/remove-list-member.mdx | 4 +- enterprise-api/lists/update-list.mdx | 4 +- enterprise-api/llms.txt | 395 + .../get-marketplace-handle-availability.mdx | 3 +- enterprise-api/media/append-media-upload.mdx | 3 +- .../media/create-media-metadata.mdx | 3 +- .../media/create-media-subtitles.mdx | 3 +- .../media/delete-media-subtitles.mdx | 3 +- .../media/finalize-media-upload.mdx | 3 +- enterprise-api/media/get-media-analytics.mdx | 3 +- .../media/get-media-by-media-key.mdx | 3 +- .../media/get-media-by-media-keys.mdx | 3 +- .../media/get-media-upload-status.mdx | 3 +- .../media/initialize-media-upload.mdx | 3 +- enterprise-api/media/introduction.mdx | 3 +- .../media/quickstart/best-practices.mdx | 3 +- enterprise-api/media/upload-media.mdx | 3 +- .../migrate/data-format-migration.mdx | 931 --- enterprise-api/migrate/overview.mdx | 212 - enterprise-api/migrate/ready-to-migrate.mdx | 0 enterprise-api/migrate/x-api-endpoint-map.mdx | 67 - .../news/get-news-stories-by-id.mdx | 3 +- enterprise-api/news/introduction.mdx | 3 +- enterprise-api/news/search-news.mdx | 3 +- enterprise-api/posts/bookmarks/integrate.mdx | 93 +- .../posts/counts/integrate/build-a-query.mdx | 93 +- .../posts/counts/integrate/overview.mdx | 2 - .../migrate/enterprise-to-twitter-api-v2.mdx | 79 +- enterprise-api/posts/create-or-edit-post.mdx | 3 +- enterprise-api/posts/create-post.mdx | 3 +- enterprise-api/posts/delete-post.mdx | 3 +- .../integrate/matching-returned-tweets.mdx | 3 +- .../filtered-stream/migrate/overview.mdx | 2 +- ...rtrack-api-migration-to-twitter-api-v2.mdx | 142 +- .../migrate/standard-to-twitter-api-v2.mdx | 109 +- .../posts/get-28-hour-post-insights.mdx | 3 +- .../posts/get-count-of-all-posts.mdx | 3 +- .../posts/get-count-of-recent-posts.mdx | 3 +- .../posts/get-historical-post-insights.mdx | 3 +- enterprise-api/posts/get-liking-users.mdx | 3 +- enterprise-api/posts/get-post-analytics.mdx | 3 +- enterprise-api/posts/get-post-by-id.mdx | 3 +- enterprise-api/posts/get-posts-by-ids.mdx | 3 +- enterprise-api/posts/get-quoted-posts.mdx | 3 +- enterprise-api/posts/get-reposted-by.mdx | 3 +- enterprise-api/posts/get-reposts.mdx | 3 +- enterprise-api/posts/hide-replies/apps.mdx | 125 +- .../integrate/manage-replies-by-topic.mdx | 3 +- .../integrate/manage-replies-in-realtime.mdx | 3 +- enterprise-api/posts/hide-replies/migrate.mdx | 2 + enterprise-api/posts/hide-reply.mdx | 3 +- ...ikes-lookup-standard-to-twitter-api-v2.mdx | 173 +- ...anage-likes-standard-to-twitter-api-v2.mdx | 225 +- .../posts/likes/migrate/overview.mdx | 2 +- enterprise-api/posts/lookup/integrate.mdx | 1 - .../posts/lookup/migrate/overview.mdx | 1 + .../migrate/standard-to-twitter-api-v2.mdx | 217 +- .../posts/manage-tweets/integrate.mdx | 1 + .../posts/manage-tweets/migrate/overview.mdx | 2 +- .../migrate/standard-to-twitter-api-v2.mdx | 109 +- enterprise-api/posts/retweets/integrate.mdx | 2 - ...ge-retweets-standard-to-twitter-api-v2.mdx | 369 +- .../posts/retweets/migrate/overview.mdx | 2 +- ...eets-lookup-standard-to-twitter-api-v2.mdx | 104 +- enterprise-api/posts/search-all-posts.mdx | 3 +- enterprise-api/posts/search-recent-posts.mdx | 3 +- .../posts/search/integrate/paginate.mdx | 3 +- .../migrate/enterprise-to-twitter-api-v2.mdx | 78 +- .../posts/search/migrate/overview.mdx | 2 - .../migrate/standard-to-twitter-api-v2.mdx | 213 +- enterprise-api/posts/timelines/integrate.mdx | 1 - .../posts/timelines/migrate/overview.mdx | 15 +- .../migrate/standard-to-twitter-api-v2.mdx | 225 +- .../powerstream/handling-disconnections.mdx | 2 + enterprise-api/powerstream/introduction.mdx | 282 +- enterprise-api/spaces/get-space-by-id.mdx | 3 +- enterprise-api/spaces/get-space-posts.mdx | 3 +- .../spaces/get-space-ticket-buyers.mdx | 3 +- .../spaces/get-spaces-by-creator-ids.mdx | 3 +- enterprise-api/spaces/get-spaces-by-ids.mdx | 3 +- enterprise-api/spaces/introduction.mdx | 3 +- enterprise-api/spaces/search-spaces.mdx | 3 +- .../stream/get-stream-rule-counts.mdx | 3 +- enterprise-api/stream/get-stream-rules.mdx | 3 +- .../stream/stream-10-sampled-posts.mdx | 3 +- enterprise-api/stream/stream-all-likes.mdx | 3 +- enterprise-api/stream/stream-all-posts.mdx | 3 +- .../stream/stream-english-posts.mdx | 3 +- .../stream/stream-filtered-posts.mdx | 3 +- .../stream/stream-japanese-posts.mdx | 3 +- enterprise-api/stream/stream-korean-posts.mdx | 3 +- .../stream/stream-likes-compliance-data.mdx | 3 +- .../stream/stream-portuguese-posts.mdx | 3 +- enterprise-api/stream/stream-post-labels.mdx | 3 +- .../stream/stream-posts-compliance-data.mdx | 3 +- .../stream/stream-sampled-likes.mdx | 3 +- .../stream/stream-sampled-posts.mdx | 3 +- .../stream/stream-users-compliance-data.mdx | 3 +- enterprise-api/stream/update-stream-rules.mdx | 3 +- enterprise-api/trends/get-ai-trends-by-id.mdx | 3 +- .../trends/get-personalized-trends.mdx | 3 +- enterprise-api/trends/get-trends-by-woeid.mdx | 3 +- enterprise-api/usage/get-usage.mdx | 3 +- enterprise-api/users/block-dms.mdx | 3 +- enterprise-api/users/blocks/integrate.mdx | 1 - enterprise-api/users/blocks/migrate.mdx | 195 +- enterprise-api/users/create-bookmark.mdx | 3 +- enterprise-api/users/delete-bookmark.mdx | 3 +- enterprise-api/users/follow-list.mdx | 3 +- enterprise-api/users/follow-user.mdx | 3 +- .../users/follows/migrate/overview.mdx | 2 +- .../migrate/standard-to-twitter-api-v2.mdx | 244 +- enterprise-api/users/get-affiliates.mdx | 3 +- enterprise-api/users/get-blocking.mdx | 3 +- enterprise-api/users/get-bookmark-folders.mdx | 3 +- .../users/get-bookmarks-by-folder-id.mdx | 3 +- enterprise-api/users/get-bookmarks.mdx | 3 +- enterprise-api/users/get-followed-lists.mdx | 3 +- enterprise-api/users/get-followers.mdx | 3 +- enterprise-api/users/get-following.mdx | 3 +- enterprise-api/users/get-liked-posts.mdx | 3 +- enterprise-api/users/get-list-memberships.mdx | 3 +- enterprise-api/users/get-mentions.mdx | 3 +- enterprise-api/users/get-muting.mdx | 3 +- enterprise-api/users/get-my-user.mdx | 3 +- enterprise-api/users/get-owned-lists.mdx | 3 +- enterprise-api/users/get-pinned-lists.mdx | 3 +- enterprise-api/users/get-posts.mdx | 3 +- .../get-public-keys-for-multiple-users.mdx | 3 +- enterprise-api/users/get-reposts-of-me.mdx | 3 +- enterprise-api/users/get-timeline.mdx | 3 +- enterprise-api/users/get-user-by-id.mdx | 3 +- enterprise-api/users/get-user-by-username.mdx | 3 +- enterprise-api/users/get-user-public-keys.mdx | 3 +- enterprise-api/users/get-users-by-ids.mdx | 3 +- .../users/get-users-by-usernames.mdx | 3 +- enterprise-api/users/like-post.mdx | 3 +- enterprise-api/users/lookup/integrate.mdx | 1 - .../users/lookup/migrate/overview.mdx | 2 +- .../migrate/standard-to-twitter-api-v2.mdx | 197 +- enterprise-api/users/mute-user.mdx | 3 +- enterprise-api/users/mutes/integrate.mdx | 1 - ...anage-mutes-standard-to-twitter-api-v2.mdx | 241 +- ...utes-lookup-standard-to-twitter-api-v2.mdx | 135 +- .../users/mutes/migrate/overview.mdx | 2 +- enterprise-api/users/pin-list.mdx | 3 +- enterprise-api/users/repost-post.mdx | 3 +- enterprise-api/users/search-users.mdx | 3 +- enterprise-api/users/unblock-dms.mdx | 3 +- enterprise-api/users/unfollow-list.mdx | 3 +- enterprise-api/users/unfollow-user.mdx | 3 +- enterprise-api/users/unlike-post.mdx | 3 +- enterprise-api/users/unmute-user.mdx | 3 +- enterprise-api/users/unpin-list.mdx | 3 +- enterprise-api/users/unrepost-post.mdx | 3 +- .../create-replay-job-for-webhook.mdx | 3 +- .../webhooks/create-stream-link.mdx | 3 +- enterprise-api/webhooks/create-webhook.mdx | 3 +- .../webhooks/delete-stream-link.mdx | 3 +- enterprise-api/webhooks/delete-webhook.mdx | 3 +- enterprise-api/webhooks/get-stream-links.mdx | 3 +- enterprise-api/webhooks/get-webhook.mdx | 3 +- .../webhooks/stream/introduction.mdx | 3 +- enterprise-api/webhooks/stream/quickstart.mdx | 3 +- enterprise-api/webhooks/validate-webhook.mdx | 3 +- fundamentals/authentication/basic-auth.mdx | 3 +- fundamentals/authentication/faq.mdx | 3 +- .../guides/authentication-best-practices.mdx | 3 +- .../authentication/guides/log-in-with-x.mdx | 14 +- fundamentals/authentication/guides/tls.mdx | 3 +- .../guides/v2-authentication-mapping.mdx | 9 +- .../oauth-1-0a/api-key-and-secret.mdx | 3 +- .../oauth-1-0a/authorizing-a-request.mdx | 3 +- .../oauth-1-0a/creating-a-signature.mdx | 3 +- .../authentication/oauth-1-0a/oauth-echo.mdx | 3 +- .../obtaining-user-access-tokens.mdx | 3 +- .../authentication/oauth-1-0a/overview.mdx | 3 +- .../percent-encoding-parameters.mdx | 3 +- .../oauth-1-0a/pin-based-oauth.mdx | 3 +- .../oauth-2-0/application-only.mdx | 2 + .../oauth-2-0/authorization-code.mdx | 3 +- .../oauth-2-0/bearer-tokens.mdx | 3 +- .../authentication/oauth-2-0/overview.mdx | 3 +- .../oauth-2-0/user-access-token.mdx | 3 +- fundamentals/authentication/overview.mdx | 3 +- llms.txt | 38 + status.mdx | 1 + tools/ai.mdx | 27 +- tools/llms-txt.mdx | 23 +- tools/skill-md.mdx | 4 - x-ads-api/analytics.mdx | 9 +- x-ads-api/audiences.mdx | 35 +- x-ads-api/campaign-management.mdx | 6401 +---------------- x-ads-api/campaign-management/reference.mdx | 6314 ++++++++++++++++ x-ads-api/catalog-management.mdx | 3 +- x-ads-api/creatives.mdx | 11 +- .../fundamentals/accessing-ads-accounts.mdx | 9 +- x-ads-api/fundamentals/currency.mdx | 3 +- .../error-codes-and-responses.mdx | 5 +- .../hierarchy-and-terminology.mdx | 5 +- .../making-authenticated-requests.mdx | 7 +- x-ads-api/fundamentals/pagination.mdx | 3 +- x-ads-api/fundamentals/rate-limiting.mdx | 5 +- x-ads-api/fundamentals/sandbox.mdx | 17 +- x-ads-api/fundamentals/sorting.mdx | 36 +- x-ads-api/fundamentals/timezones.mdx | 5 +- x-ads-api/fundamentals/versioning.mdx | 324 +- .../getting-started/increasing-access.mdx | 2 + .../getting-started/step-by-step-guide.mdx | 2 + .../getting-started/subscribe-for-updates.mdx | 3 +- x-ads-api/introduction.mdx | 1 + x-ads-api/llms.txt | 42 + x-ads-api/measurement/ab-testing.mdx | 613 +- x-ads-api/measurement/mobile-conversions.mdx | 573 +- x-ads-api/measurement/web-conversions.mdx | 580 +- x-ads-api/tools-and-libraries.mdx | 2 + x-api/account-activity/create-replay-job.mdx | 3 +- .../account-activity/create-subscription.mdx | 3 +- .../account-activity/delete-subscription.mdx | 3 +- .../get-subscription-count.mdx | 3 +- x-api/account-activity/get-subscriptions.mdx | 3 +- x-api/account-activity/migrate/overview.mdx | 2 +- .../validate-subscription.mdx | 3 +- x-api/activity/activity-stream.mdx | 3 +- .../create-x-activity-subscription.mdx | 3 +- ...delete-x-activity-subscriptions-by-ids.mdx | 3 +- .../deletes-x-activity-subscription.mdx | 3 +- .../activity/get-x-activity-subscriptions.mdx | 3 +- x-api/activity/introduction.mdx | 24 +- .../update-x-activity-subscription.mdx | 3 +- x-api/bookmarks/create-bookmark.mdx | 3 +- x-api/bookmarks/delete-bookmark.mdx | 3 +- x-api/bookmarks/get-bookmark-folders.mdx | 3 +- .../bookmarks/get-bookmarks-by-folder-id.mdx | 3 +- x-api/bookmarks/get-bookmarks.mdx | 3 +- ...d-members-to-a-chat-group-conversation.mdx | 3 +- x-api/chat/add-public-key.mdx | 3 +- x-api/chat/append-chat-media-upload.mdx | 3 +- x-api/chat/create-chat-group-conversation.mdx | 3 +- x-api/chat/download-chat-media.mdx | 3 +- x-api/chat/finalize-chat-media-upload.mdx | 3 +- x-api/chat/get-chat-conversation.mdx | 3 +- x-api/chat/get-chat-conversations.mdx | 3 +- x-api/chat/get-user-public-keys.mdx | 3 +- x-api/chat/initialize-chat-group.mdx | 3 +- x-api/chat/initialize-chat-media-upload.mdx | 3 +- x-api/chat/initialize-conversation-keys.mdx | 3 +- x-api/chat/mark-conversation-as-read.mdx | 3 +- x-api/chat/send-chat-message.mdx | 3 +- x-api/chat/send-typing-indicator.mdx | 3 +- x-api/communities/get-community-by-id.mdx | 3 +- x-api/communities/search-communities.mdx | 3 +- .../create-a-community-note.mdx | 3 +- .../delete-a-community-note.mdx | 3 +- .../evaluate-a-community-note.mdx | 3 +- x-api/community-notes/introduction.mdx | 3 +- .../search-for-community-notes-written.mdx | 3 +- ...for-posts-eligible-for-community-notes.mdx | 3 +- .../compliance/batch-compliance/integrate.mdx | 250 +- x-api/compliance/create-compliance-job.mdx | 3 +- x-api/compliance/get-compliance-job-by-id.mdx | 3 +- x-api/compliance/get-compliance-jobs.mdx | 3 +- x-api/compliance/streams/introduction.mdx | 160 +- x-api/connections/get-connection-history.mdx | 3 +- .../connections/terminate-all-connections.mdx | 3 +- .../terminate-connections-by-endpoint.mdx | 3 +- .../terminate-multiple-connections.mdx | 3 +- x-api/direct-messages/blocks/introduction.mdx | 131 +- .../create-dm-conversation.mdx | 3 +- .../create-dm-message-by-conversation-id.mdx | 3 +- .../create-dm-message-by-participant-id.mdx | 3 +- x-api/direct-messages/delete-dm-event.mdx | 3 +- x-api/direct-messages/download-dm-media.mdx | 3 +- x-api/direct-messages/get-dm-event-by-id.mdx | 3 +- .../get-dm-events-for-a-dm-conversation-1.mdx | 3 +- .../get-dm-events-for-a-dm-conversation.mdx | 3 +- x-api/direct-messages/get-dm-events.mdx | 3 +- x-api/direct-messages/lookup/integrate.mdx | 543 +- x-api/direct-messages/lookup/migrate.mdx | 171 +- x-api/direct-messages/manage/integrate.mdx | 579 +- x-api/direct-messages/manage/migrate.mdx | 163 +- x-api/enterprise-gnip-2.0/enterprise-gnip.mdx | 3 +- .../fundamentals/account-activity.mdx | 1946 +---- .../fundamentals/data-enrichments.mdx | 25 +- .../fundamentals/decahose-api.mdx | 158 +- .../fundamentals/edit-tweets.mdx | 3 +- .../fundamentals/engagement-api.mdx | 686 +- .../fundamentals/firehouse.mdx | 110 +- .../fundamentals/overview.mdx | 3 +- .../fundamentals/rate-limits.mdx | 3 +- .../fundamentals/rules-filtering.mdx | 149 +- .../fundamentals/search-api.mdx | 1347 +--- x-api/enterprise-gnip-2.0/powertrack-api.mdx | 1715 +---- x-api/general/get-openapi-spec.mdx | 3 +- x-api/lists/add-list-member.mdx | 3 +- x-api/lists/create-list.mdx | 3 +- x-api/lists/delete-list.mdx | 3 +- x-api/lists/get-list-by-id.mdx | 3 +- x-api/lists/get-list-followers.mdx | 3 +- x-api/lists/get-list-members.mdx | 3 +- x-api/lists/get-list-posts.mdx | 3 +- x-api/lists/list-lookup/integrate.mdx | 561 +- x-api/lists/list-lookup/migrate/overview.mdx | 102 +- .../migrate/standard-to-twitter-api-v2.mdx | 256 +- x-api/lists/list-members/integrate.mdx | 170 +- ...bers-lookup-standard-to-twitter-api-v2.mdx | 177 +- ...ist-members-standard-to-twitter-api-v2.mdx | 130 +- x-api/lists/list-members/migrate/overview.mdx | 160 +- x-api/lists/list-tweets/integrate.mdx | 162 +- x-api/lists/list-tweets/migrate/overview.mdx | 76 +- .../migrate/standard-to-twitter-api-v2.mdx | 350 +- x-api/lists/manage-lists/integrate.mdx | 335 +- x-api/lists/manage-lists/migrate/overview.mdx | 114 +- .../migrate/standard-to-twitter-api-v2.mdx | 273 +- x-api/lists/pinned-lists/integrate.mdx | 146 +- x-api/lists/remove-list-member.mdx | 3 +- x-api/lists/update-list.mdx | 3 +- x-api/llms.txt | 434 ++ .../get-marketplace-handle-availability.mdx | 3 +- x-api/media/append-media-upload.mdx | 3 +- x-api/media/create-media-metadata.mdx | 3 +- x-api/media/create-media-subtitles.mdx | 3 +- x-api/media/delete-media-subtitles.mdx | 3 +- x-api/media/finalize-media-upload.mdx | 3 +- x-api/media/get-media-analytics.mdx | 3 +- x-api/media/get-media-by-media-key.mdx | 3 +- x-api/media/get-media-by-media-keys.mdx | 3 +- x-api/media/get-media-upload-status.mdx | 3 +- x-api/media/initialize-media-upload.mdx | 3 +- x-api/media/introduction.mdx | 2 + x-api/media/quickstart/best-practices.mdx | 3 +- x-api/media/upload-media.mdx | 3 +- x-api/migrate/data-format-migration.mdx | 911 +-- x-api/migrate/overview.mdx | 140 +- x-api/migrate/x-api-endpoint-map.mdx | 47 +- x-api/news/get-news-stories-by-id.mdx | 3 +- x-api/news/introduction.mdx | 2 + x-api/news/search-news.mdx | 3 +- x-api/posts/bookmarks/integrate.mdx | 167 +- .../posts/counts/integrate/build-a-query.mdx | 467 +- x-api/posts/counts/integrate/overview.mdx | 112 +- .../migrate/enterprise-to-twitter-api-v2.mdx | 189 +- x-api/posts/counts/migrate/overview.mdx | 271 +- x-api/posts/create-or-edit-post.mdx | 3 +- x-api/posts/create-post.mdx | 3 +- x-api/posts/delete-post.mdx | 3 +- .../integrate/matching-returned-tweets.mdx | 97 +- .../filtered-stream/migrate/overview.mdx | 76 +- ...rtrack-api-migration-to-twitter-api-v2.mdx | 216 +- .../migrate/standard-to-twitter-api-v2.mdx | 375 +- x-api/posts/get-28-hour-post-insights.mdx | 3 +- x-api/posts/get-count-of-all-posts.mdx | 3 +- x-api/posts/get-count-of-recent-posts.mdx | 3 +- x-api/posts/get-historical-post-insights.mdx | 3 +- x-api/posts/get-liking-users.mdx | 3 +- x-api/posts/get-post-analytics.mdx | 3 +- x-api/posts/get-post-by-id.mdx | 3 +- x-api/posts/get-posts-by-ids.mdx | 3 +- x-api/posts/get-quoted-posts.mdx | 3 +- x-api/posts/get-reposted-by.mdx | 3 +- x-api/posts/get-reposts.mdx | 3 +- x-api/posts/hide-replies/apps.mdx | 125 +- .../integrate/manage-replies-by-topic.mdx | 67 +- .../integrate/manage-replies-in-realtime.mdx | 55 +- x-api/posts/hide-replies/migrate.mdx | 200 +- x-api/posts/hide-reply.mdx | 3 +- ...ikes-lookup-standard-to-twitter-api-v2.mdx | 241 +- ...anage-likes-standard-to-twitter-api-v2.mdx | 225 +- x-api/posts/likes/migrate/overview.mdx | 148 +- x-api/posts/lookup/integrate.mdx | 1 - x-api/posts/lookup/migrate/overview.mdx | 2 - .../migrate/standard-to-twitter-api-v2.mdx | 217 +- x-api/posts/manage-tweets/integrate.mdx | 4 +- .../posts/manage-tweets/migrate/overview.mdx | 2 +- .../migrate/standard-to-twitter-api-v2.mdx | 109 +- x-api/posts/retweets/integrate.mdx | 340 +- ...ge-retweets-standard-to-twitter-api-v2.mdx | 220 +- x-api/posts/retweets/migrate/overview.mdx | 120 +- ...eets-lookup-standard-to-twitter-api-v2.mdx | 176 +- x-api/posts/search-all-posts.mdx | 3 +- x-api/posts/search-recent-posts.mdx | 3 +- x-api/posts/search/integrate/paginate.mdx | 3 +- x-api/posts/search/introduction.mdx | 2 +- .../migrate/enterprise-to-twitter-api-v2.mdx | 78 +- x-api/posts/search/migrate/overview.mdx | 1 + .../migrate/standard-to-twitter-api-v2.mdx | 213 +- x-api/posts/timelines/integrate.mdx | 1 - x-api/posts/timelines/migrate/overview.mdx | 15 +- .../migrate/standard-to-twitter-api-v2.mdx | 225 +- x-api/posts/volume-streams/introduction.mdx | 125 +- x-api/powerstream/handling-disconnections.mdx | 1 + x-api/powerstream/operators.mdx | 1 - x-api/powerstream/recovery-and-redundancy.mdx | 1 + x-api/spaces/get-space-by-id.mdx | 3 +- x-api/spaces/get-space-posts.mdx | 3 +- x-api/spaces/get-space-ticket-buyers.mdx | 3 +- x-api/spaces/get-spaces-by-creator-ids.mdx | 3 +- x-api/spaces/get-spaces-by-ids.mdx | 3 +- x-api/spaces/introduction.mdx | 2 + x-api/spaces/search-spaces.mdx | 3 +- x-api/stream/get-stream-rule-counts.mdx | 3 +- x-api/stream/get-stream-rules.mdx | 3 +- x-api/stream/stream-10-sampled-posts.mdx | 3 +- x-api/stream/stream-all-likes.mdx | 3 +- x-api/stream/stream-all-posts.mdx | 3 +- x-api/stream/stream-english-posts.mdx | 3 +- x-api/stream/stream-filtered-posts.mdx | 3 +- x-api/stream/stream-japanese-posts.mdx | 3 +- x-api/stream/stream-korean-posts.mdx | 3 +- x-api/stream/stream-likes-compliance-data.mdx | 3 +- x-api/stream/stream-portuguese-posts.mdx | 3 +- x-api/stream/stream-post-labels.mdx | 3 +- x-api/stream/stream-posts-compliance-data.mdx | 3 +- x-api/stream/stream-sampled-likes.mdx | 3 +- x-api/stream/stream-sampled-posts.mdx | 3 +- x-api/stream/stream-users-compliance-data.mdx | 3 +- x-api/stream/update-stream-rules.mdx | 3 +- x-api/trends/get-ai-trends-by-id.mdx | 3 +- x-api/trends/get-personalized-trends.mdx | 3 +- x-api/trends/get-trends-by-woeid.mdx | 3 +- x-api/usage/get-usage.mdx | 3 +- x-api/users/block-dms.mdx | 3 +- x-api/users/blocks/integrate.mdx | 1 - x-api/users/blocks/migrate.mdx | 1 + x-api/users/create-bookmark.mdx | 3 +- x-api/users/delete-bookmark.mdx | 3 +- x-api/users/follow-list.mdx | 3 +- x-api/users/follow-user.mdx | 3 +- x-api/users/follows/migrate/overview.mdx | 144 +- .../migrate/standard-to-twitter-api-v2.mdx | 244 +- x-api/users/get-affiliates.mdx | 3 +- x-api/users/get-blocking.mdx | 3 +- x-api/users/get-bookmark-folders.mdx | 3 +- x-api/users/get-bookmarks-by-folder-id.mdx | 3 +- x-api/users/get-bookmarks.mdx | 3 +- x-api/users/get-followed-lists.mdx | 3 +- x-api/users/get-followers.mdx | 3 +- x-api/users/get-following.mdx | 3 +- x-api/users/get-liked-posts.mdx | 3 +- x-api/users/get-list-memberships.mdx | 3 +- x-api/users/get-mentions.mdx | 3 +- x-api/users/get-muting.mdx | 3 +- x-api/users/get-my-user.mdx | 3 +- x-api/users/get-owned-lists.mdx | 3 +- x-api/users/get-pinned-lists.mdx | 3 +- x-api/users/get-posts.mdx | 3 +- .../get-public-keys-for-multiple-users.mdx | 3 +- x-api/users/get-reposts-of-me.mdx | 3 +- x-api/users/get-timeline.mdx | 3 +- x-api/users/get-user-by-id.mdx | 3 +- x-api/users/get-user-by-username.mdx | 3 +- x-api/users/get-user-public-keys.mdx | 3 +- x-api/users/get-users-by-ids.mdx | 3 +- x-api/users/get-users-by-usernames.mdx | 3 +- x-api/users/like-post.mdx | 3 +- x-api/users/lookup/integrate.mdx | 737 +- x-api/users/lookup/migrate/overview.mdx | 78 +- .../migrate/standard-to-twitter-api-v2.mdx | 267 +- x-api/users/mute-user.mdx | 3 +- x-api/users/mutes/integrate.mdx | 473 +- ...anage-mutes-standard-to-twitter-api-v2.mdx | 241 +- ...utes-lookup-standard-to-twitter-api-v2.mdx | 221 +- x-api/users/mutes/migrate/overview.mdx | 124 +- x-api/users/pin-list.mdx | 3 +- x-api/users/repost-post.mdx | 3 +- x-api/users/search-users.mdx | 3 +- x-api/users/unblock-dms.mdx | 3 +- x-api/users/unfollow-list.mdx | 3 +- x-api/users/unfollow-user.mdx | 3 +- x-api/users/unlike-post.mdx | 3 +- x-api/users/unmute-user.mdx | 3 +- x-api/users/unpin-list.mdx | 3 +- x-api/users/unrepost-post.mdx | 3 +- .../create-replay-job-for-webhook.mdx | 3 +- x-api/webhooks/create-stream-link.mdx | 3 +- x-api/webhooks/create-webhook.mdx | 3 +- x-api/webhooks/delete-stream-link.mdx | 3 +- x-api/webhooks/delete-webhook.mdx | 3 +- x-api/webhooks/get-stream-links.mdx | 3 +- x-api/webhooks/get-webhook.mdx | 3 +- x-api/webhooks/stream/introduction.mdx | 3 +- x-api/webhooks/stream/quickstart.mdx | 3 +- x-api/webhooks/validate-webhook.mdx | 3 +- xdks/llms.txt | 11 + xdks/python/authentication.mdx | 3 +- xdks/python/install.mdx | 2 + xdks/python/llms.txt | 78 + xdks/python/overview.mdx | 1 + xdks/python/pagination.mdx | 3 +- xdks/python/quickstart.mdx | 2 + xdks/python/streaming.mdx | 3 +- xdks/typescript/authentication.mdx | 3 +- xdks/typescript/install.mdx | 2 + xdks/typescript/llms.txt | 115 + xdks/typescript/overview.mdx | 1 + xdks/typescript/pagination.mdx | 3 +- xdks/typescript/streaming.mdx | 3 +- 617 files changed, 14196 insertions(+), 48817 deletions(-) create mode 100644 .well-known/llms.txt create mode 100644 AGENT.md create mode 100644 AGENTS.md delete mode 100644 enterprise-api/enterprise-gnip-2.0/enterprise-gnip.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/account-activity.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/data-dictionary.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/data-enrichments.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/decahose-api.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/edit-tweets.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/engagement-api.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/firehouse.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/overview.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/rate-limits.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/rules-filtering.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/search-api.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/fundamentals/usage.mdx delete mode 100644 enterprise-api/enterprise-gnip-2.0/powertrack-api.mdx delete mode 100644 enterprise-api/fundamentals/consistency.mdx delete mode 100644 enterprise-api/fundamentals/consuming-streaming-data.mdx delete mode 100644 enterprise-api/fundamentals/conversation-id.mdx delete mode 100644 enterprise-api/fundamentals/data-dictionary.mdx delete mode 100644 enterprise-api/fundamentals/edit-posts.mdx delete mode 100644 enterprise-api/fundamentals/expansions.mdx delete mode 100644 enterprise-api/fundamentals/fields.mdx delete mode 100644 enterprise-api/fundamentals/handling-disconnections.mdx delete mode 100644 enterprise-api/fundamentals/high-volume-capacity.mdx delete mode 100644 enterprise-api/fundamentals/metrics.mdx delete mode 100644 enterprise-api/fundamentals/pagination.mdx delete mode 100644 enterprise-api/fundamentals/post-annotations.mdx delete mode 100644 enterprise-api/fundamentals/post-cap.mdx delete mode 100644 enterprise-api/fundamentals/rate-limits.mdx delete mode 100644 enterprise-api/fundamentals/recovery-and-redundancy.mdx delete mode 100644 enterprise-api/fundamentals/response-codes-and-errors.mdx delete mode 100644 enterprise-api/fundamentals/versioning.mdx create mode 100644 enterprise-api/llms.txt delete mode 100644 enterprise-api/migrate/data-format-migration.mdx delete mode 100644 enterprise-api/migrate/overview.mdx delete mode 100644 enterprise-api/migrate/ready-to-migrate.mdx delete mode 100644 enterprise-api/migrate/x-api-endpoint-map.mdx create mode 100644 llms.txt create mode 100644 x-ads-api/campaign-management/reference.mdx create mode 100644 x-ads-api/llms.txt create mode 100644 x-api/llms.txt create mode 100644 xdks/llms.txt create mode 100644 xdks/python/llms.txt create mode 100644 xdks/typescript/llms.txt diff --git a/.well-known/llms.txt b/.well-known/llms.txt new file mode 100644 index 000000000..cbc5d3547 --- /dev/null +++ b/.well-known/llms.txt @@ -0,0 +1,37 @@ +# X Developer Platform + +> Build, analyze, and innovate with X's real-time, global data and APIs. Comprehensive documentation for the X API v2, Ads API, Enterprise APIs (Account Activity, X Activity, GNIP/PowerTrack), official SDKs, tutorials, and AI-agent tools (llms.txt, skill.md, MCP). + +## Start Here + +- [Overview](https://docs.x.com/overview.md): Introduction to the X Developer Platform +- [Getting Access & First Request](https://docs.x.com/make-your-first-request.md): Quickstart for new developers +- [What to Build](https://docs.x.com/what-to-build.md): Use-case ideas and inspiration +- [Developer Guidelines & Policies](https://docs.x.com/developer-guidelines.md): Rules for building responsibly +- [AI & Agent Resources](https://docs.x.com/tools/ai.md): llms.txt, skill.md, MCP, and Grok/Cursor integration + +## Major Documentation Areas (Nested Indexes) + +- [X API v2 — Full Index](https://docs.x.com/x-api/llms.txt): 370+ reference pages (Posts, Users, DMs, Lists, Spaces, Streams, Compliance, Webhooks, Media, etc.) +- [Enterprise APIs — Full Index](https://docs.x.com/enterprise-api/llms.txt): Account Activity, X Activity (XAA), Compliance, Chat, Communities, Direct Messages, News, Trends, Webhooks, and historical GNIP/PowerTrack +- [Ads API — Full Index](https://docs.x.com/x-ads-api/llms.txt): Campaign management, creatives, audiences, analytics, measurement, and conversions +- [Python SDK (XDK) — Full Index](https://docs.x.com/xdks/python/llms.txt): Complete Python client, models, paginators, and streaming reference +- [TypeScript SDK (XDK) — Full Index](https://docs.x.com/xdks/typescript/llms.txt): Full TypeScript/JavaScript client and 300+ model/interface references + +## Key Fundamentals & Tools + +- [X API Fundamentals](https://docs.x.com/x-api/fundamentals/data-dictionary.md): Fields, expansions, pagination, versioning, consistency, rate limits +- [Authentication Guides](https://docs.x.com/fundamentals/authentication/overview.md): OAuth 1.0a, OAuth 2.0, Bearer tokens, app-only, user context +- [Tools & Libraries](https://docs.x.com/tools-and-libraries.md): Official SDKs, Postman, twurl, xurl +- [Changelog](https://docs.x.com/changelog.md): Platform updates and new endpoints +- [Tutorials](https://docs.x.com/tutorials.md): In-depth code examples and integration guides + +## For AI Agents & LLMs + +- [llms-full.txt](https://docs.x.com/llms-full.txt): Entire documentation set as a single Markdown file (maximum context) +- [Raw Markdown for any page](https://docs.x.com/tools/llms-txt.md): Append `.md` to any docs.x.com URL (example: https://docs.x.com/x-api/posts/get-post-by-id.md) +- [skill.md](https://docs.x.com/tools/skill-md.md): Structured capability description for agents (agentskills.io spec) +- [MCP Server](https://docs.x.com/tools/mcp.md): Model Context Protocol server exposing X API tools to AI agents +- [OpenAPI Specification](https://docs.x.com/openapi.json): Machine-readable API contract + +All pages are also available under `/.well-known/llms.txt`. Every documentation page supports the `.md` suffix for clean Markdown retrieval by agents. diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 000000000..72a64a77a --- /dev/null +++ b/AGENT.md @@ -0,0 +1,74 @@ +# X Developer Platform — Agent Instructions + +This document provides guidance for AI agents, coding assistants, and LLM-based tools interacting with the X Developer Platform documentation at https://docs.x.com. + +## Preferred Documentation Access Methods + +**Always prefer these methods for the most accurate, up-to-date, and agent-friendly content:** + +1. **llms.txt** (recommended starting point) + - https://docs.x.com/llms.txt — Small, curated root index with links to section-specific indexes. + - Section indexes (follow the links in the root): + - https://docs.x.com/x-api/llms.txt (X API v2 — 370+ pages) + - https://docs.x.com/enterprise-api/llms.txt + - https://docs.x.com/x-ads-api/llms.txt + - https://docs.x.com/xdks/llms.txt (Python + TypeScript XDKs) + +2. **llms-full.txt** — Complete documentation as a single Markdown file for maximum context: + - https://docs.x.com/llms-full.txt + +3. **Raw Markdown for any individual page** + - Append `.md` to any documentation URL. + - Example: `https://docs.x.com/x-api/posts/get-post-by-id.md` + - Every page supports this. Use it instead of the HTML view when possible. + +4. **MCP Server** (for tool-using agents) + - https://docs.x.com/tools/mcp — Full Model Context Protocol server exposing 200+ X API endpoints + documentation search. + +5. **skill.md** (capability summary) + - https://docs.x.com/skill.md — Structured description of every action an agent can perform with the X API (agentskills.io format). + +## Site Structure & Navigation + +- **X API v2** (`/x-api/...`): Posts, Users, Direct Messages, Lists, Spaces, Media, Streams (filtered + volume), Compliance, Webhooks, Account Activity, Trends, News, Usage, Connections. +- **Enterprise APIs** (`/enterprise-api/...`): Account Activity (webhooks), X Activity (XAA), GNIP/PowerTrack historical & real-time, Compliance. +- **Ads API** (`/x-ads-api/...`): Campaign Management, Creatives, Audiences, Analytics, Measurement, Catalog. +- **SDKs (XDKs)** (`/xdks/python/...` and `/xdks/typescript/...`): Official client libraries with full type coverage, pagination, and streaming helpers. +- **Fundamentals**: Authentication, rate limits, data dictionary, expansions, fields, pagination, versioning, consistency. +- **AI & Agent Tools** (`/tools/ai`, `/tools/llms-txt`, `/tools/skill-md`, `/tools/mcp`). + +All pages are available in the navigation tree defined in `docs.json`. + +## Important Technical Notes for Agents + +- **Authentication**: The platform supports OAuth 1.0a (user context), OAuth 2.0 (user context + PKCE, app-only Bearer), and Basic Auth for some enterprise endpoints. See `/fundamentals/authentication/...`. +- **Rate Limits**: Most endpoints have both app-level and user-level rate limits. See `/fundamentals/rate-limits.md` and per-endpoint documentation. +- **Data Model**: Use the official data dictionary, fields, expansions, and metrics pages. Posts, Users, and Spaces are the core objects. +- **Real-time Data**: Filtered Stream, Volume Streams, Account Activity webhooks, and X Activity (XAA) are the primary real-time mechanisms. +- **Compliance & Safety**: Always respect developer terms, display requirements, and restricted use cases. See `/developer-guidelines.md` and `/developer-terms/...`. + +## How to Use This Documentation Effectively + +- Start with the root `llms.txt` to discover relevant pages. +- Fetch individual pages via the `.md` suffix for clean, structured Markdown. +- For deep context on the entire platform, load `llms-full.txt`. +- For structured capabilities (what actions are possible), load `skill.md`. +- For live tool calling against the X API, use the MCP server. +- When writing code, prefer the official Python or TypeScript XDKs (full references available in their `llms.txt` files). + +## Do Not + +- Rely solely on the HTML-rendered pages when a clean Markdown alternative exists. +- Assume deprecated v1.1 endpoints are still primary (focus on v2 and Enterprise equivalents). +- Ignore rate limits, authentication context (app-only vs user context), or pagination requirements. +- Generate code that violates the X Developer Agreement or Display Requirements. + +## Additional Resources + +- OpenAPI spec: https://docs.x.com/openapi.json (or https://api.x.com/2/openapi.json) +- Changelog: https://docs.x.com/changelog.md +- Status page: https://docs.x.com/status.md +- Developer Guidelines: https://docs.x.com/developer-guidelines.md +- Support & Community: https://devcommunity.x.com + +This documentation is designed to be consumed reliably by AI agents. Use the machine-readable formats (`llms.txt` family, `.md` suffix, `skill.md`, MCP) for the best results. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..72a64a77a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ +# X Developer Platform — Agent Instructions + +This document provides guidance for AI agents, coding assistants, and LLM-based tools interacting with the X Developer Platform documentation at https://docs.x.com. + +## Preferred Documentation Access Methods + +**Always prefer these methods for the most accurate, up-to-date, and agent-friendly content:** + +1. **llms.txt** (recommended starting point) + - https://docs.x.com/llms.txt — Small, curated root index with links to section-specific indexes. + - Section indexes (follow the links in the root): + - https://docs.x.com/x-api/llms.txt (X API v2 — 370+ pages) + - https://docs.x.com/enterprise-api/llms.txt + - https://docs.x.com/x-ads-api/llms.txt + - https://docs.x.com/xdks/llms.txt (Python + TypeScript XDKs) + +2. **llms-full.txt** — Complete documentation as a single Markdown file for maximum context: + - https://docs.x.com/llms-full.txt + +3. **Raw Markdown for any individual page** + - Append `.md` to any documentation URL. + - Example: `https://docs.x.com/x-api/posts/get-post-by-id.md` + - Every page supports this. Use it instead of the HTML view when possible. + +4. **MCP Server** (for tool-using agents) + - https://docs.x.com/tools/mcp — Full Model Context Protocol server exposing 200+ X API endpoints + documentation search. + +5. **skill.md** (capability summary) + - https://docs.x.com/skill.md — Structured description of every action an agent can perform with the X API (agentskills.io format). + +## Site Structure & Navigation + +- **X API v2** (`/x-api/...`): Posts, Users, Direct Messages, Lists, Spaces, Media, Streams (filtered + volume), Compliance, Webhooks, Account Activity, Trends, News, Usage, Connections. +- **Enterprise APIs** (`/enterprise-api/...`): Account Activity (webhooks), X Activity (XAA), GNIP/PowerTrack historical & real-time, Compliance. +- **Ads API** (`/x-ads-api/...`): Campaign Management, Creatives, Audiences, Analytics, Measurement, Catalog. +- **SDKs (XDKs)** (`/xdks/python/...` and `/xdks/typescript/...`): Official client libraries with full type coverage, pagination, and streaming helpers. +- **Fundamentals**: Authentication, rate limits, data dictionary, expansions, fields, pagination, versioning, consistency. +- **AI & Agent Tools** (`/tools/ai`, `/tools/llms-txt`, `/tools/skill-md`, `/tools/mcp`). + +All pages are available in the navigation tree defined in `docs.json`. + +## Important Technical Notes for Agents + +- **Authentication**: The platform supports OAuth 1.0a (user context), OAuth 2.0 (user context + PKCE, app-only Bearer), and Basic Auth for some enterprise endpoints. See `/fundamentals/authentication/...`. +- **Rate Limits**: Most endpoints have both app-level and user-level rate limits. See `/fundamentals/rate-limits.md` and per-endpoint documentation. +- **Data Model**: Use the official data dictionary, fields, expansions, and metrics pages. Posts, Users, and Spaces are the core objects. +- **Real-time Data**: Filtered Stream, Volume Streams, Account Activity webhooks, and X Activity (XAA) are the primary real-time mechanisms. +- **Compliance & Safety**: Always respect developer terms, display requirements, and restricted use cases. See `/developer-guidelines.md` and `/developer-terms/...`. + +## How to Use This Documentation Effectively + +- Start with the root `llms.txt` to discover relevant pages. +- Fetch individual pages via the `.md` suffix for clean, structured Markdown. +- For deep context on the entire platform, load `llms-full.txt`. +- For structured capabilities (what actions are possible), load `skill.md`. +- For live tool calling against the X API, use the MCP server. +- When writing code, prefer the official Python or TypeScript XDKs (full references available in their `llms.txt` files). + +## Do Not + +- Rely solely on the HTML-rendered pages when a clean Markdown alternative exists. +- Assume deprecated v1.1 endpoints are still primary (focus on v2 and Enterprise equivalents). +- Ignore rate limits, authentication context (app-only vs user context), or pagination requirements. +- Generate code that violates the X Developer Agreement or Display Requirements. + +## Additional Resources + +- OpenAPI spec: https://docs.x.com/openapi.json (or https://api.x.com/2/openapi.json) +- Changelog: https://docs.x.com/changelog.md +- Status page: https://docs.x.com/status.md +- Developer Guidelines: https://docs.x.com/developer-guidelines.md +- Support & Community: https://devcommunity.x.com + +This documentation is designed to be consumed reliably by AI agents. Use the machine-readable formats (`llms.txt` family, `.md` suffix, `skill.md`, MCP) for the best results. diff --git a/docs.json b/docs.json index c0b085200..efdb7fc60 100644 --- a/docs.json +++ b/docs.json @@ -1029,7 +1029,8 @@ { "group": "Campaign Management", "pages": [ - "x-ads-api/campaign-management" + "x-ads-api/campaign-management", + "x-ads-api/campaign-management/reference" ] }, "x-ads-api/catalog-management", diff --git a/enterprise-api/account-activity/create-replay-job.mdx b/enterprise-api/account-activity/create-replay-job.mdx index 5ea81d60f..cca4780f5 100644 --- a/enterprise-api/account-activity/create-replay-job.mdx +++ b/enterprise-api/account-activity/create-replay-job.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/account_activity/replay/webhooks/{webhook_id}/subscriptions/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/account-activity/create-subscription.mdx b/enterprise-api/account-activity/create-subscription.mdx index b9c8294ba..6a19077fe 100644 --- a/enterprise-api/account-activity/create-subscription.mdx +++ b/enterprise-api/account-activity/create-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/account_activity/webhooks/{webhook_id}/subscriptions/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/account-activity/delete-subscription.mdx b/enterprise-api/account-activity/delete-subscription.mdx index 9a35c11dd..6d0336df3 100644 --- a/enterprise-api/account-activity/delete-subscription.mdx +++ b/enterprise-api/account-activity/delete-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/account_activity/webhooks/{webhook_id}/subscriptions/{user_id}/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/account-activity/get-subscription-count.mdx b/enterprise-api/account-activity/get-subscription-count.mdx index a4969e513..ae4d0fac5 100644 --- a/enterprise-api/account-activity/get-subscription-count.mdx +++ b/enterprise-api/account-activity/get-subscription-count.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/account_activity/subscriptions/count ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/account-activity/get-subscriptions.mdx b/enterprise-api/account-activity/get-subscriptions.mdx index de6879cf8..943215d43 100644 --- a/enterprise-api/account-activity/get-subscriptions.mdx +++ b/enterprise-api/account-activity/get-subscriptions.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/account_activity/webhooks/{webhook_id}/subscriptions/all/list ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/account-activity/migrate/overview.mdx b/enterprise-api/account-activity/migrate/overview.mdx index f4afbe06a..6b909819e 100644 --- a/enterprise-api/account-activity/migrate/overview.mdx +++ b/enterprise-api/account-activity/migrate/overview.mdx @@ -1,7 +1,7 @@ --- title: v2 Account Activity API Migration Guide keywords: ["Account Activity API migration", "AAA migration", "v2 migration", "API migration guide", "migrate to v2", "Account Activity API v2"] ---- + This guide helps you migrate from the legacy Enterprise Account Activity API to the V2 Account Activity API. The core functionality remains the same, but endpoint structures and authentication methods have been updated for consistency with X API v2. diff --git a/enterprise-api/account-activity/validate-subscription.mdx b/enterprise-api/account-activity/validate-subscription.mdx index 5075d8cbc..62afd3ffe 100644 --- a/enterprise-api/account-activity/validate-subscription.mdx +++ b/enterprise-api/account-activity/validate-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/account_activity/webhooks/{webhook_id}/subscriptions/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/activity/activity-stream.mdx b/enterprise-api/activity/activity-stream.mdx index 5eb88014e..f519b9fb6 100644 --- a/enterprise-api/activity/activity-stream.mdx +++ b/enterprise-api/activity/activity-stream.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/activity/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/activity/create-x-activity-subscription.mdx b/enterprise-api/activity/create-x-activity-subscription.mdx index f11274f91..5fbf86d57 100644 --- a/enterprise-api/activity/create-x-activity-subscription.mdx +++ b/enterprise-api/activity/create-x-activity-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/activity/subscriptions ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/activity/deletes-x-activity-subscription.mdx b/enterprise-api/activity/deletes-x-activity-subscription.mdx index ffd6ddf01..05e059cbc 100644 --- a/enterprise-api/activity/deletes-x-activity-subscription.mdx +++ b/enterprise-api/activity/deletes-x-activity-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/activity/subscriptions/{subscription_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/activity/get-x-activity-subscriptions.mdx b/enterprise-api/activity/get-x-activity-subscriptions.mdx index 8de76f510..a103bfb42 100644 --- a/enterprise-api/activity/get-x-activity-subscriptions.mdx +++ b/enterprise-api/activity/get-x-activity-subscriptions.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/activity/subscriptions ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/activity/introduction.mdx b/enterprise-api/activity/introduction.mdx index 98dcf1f19..299b8cdef 100644 --- a/enterprise-api/activity/introduction.mdx +++ b/enterprise-api/activity/introduction.mdx @@ -2,7 +2,8 @@ title: Introduction sidebarTitle: Introduction keywords: ["activity API", "X Activity API", "activity events", "profile updates", "user activity", "real-time events", "activity stream"] ---- + +description: The X Activity API (XAA) endpoint group allows developers to tap in to activity events happening on the X Platform. A developer can subscribe to events ...--- import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/activity/update-x-activity-subscription.mdx b/enterprise-api/activity/update-x-activity-subscription.mdx index df57b27e6..89a25c021 100644 --- a/enterprise-api/activity/update-x-activity-subscription.mdx +++ b/enterprise-api/activity/update-x-activity-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: put /2/activity/subscriptions/{subscription_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/bookmarks/create-bookmark.mdx b/enterprise-api/bookmarks/create-bookmark.mdx index 7474d20cd..62cbefe9a 100644 --- a/enterprise-api/bookmarks/create-bookmark.mdx +++ b/enterprise-api/bookmarks/create-bookmark.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/bookmarks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/bookmarks/delete-bookmark.mdx b/enterprise-api/bookmarks/delete-bookmark.mdx index 78d0e4078..22457d0af 100644 --- a/enterprise-api/bookmarks/delete-bookmark.mdx +++ b/enterprise-api/bookmarks/delete-bookmark.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/bookmarks/{tweet_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/bookmarks/get-bookmark-folders.mdx b/enterprise-api/bookmarks/get-bookmark-folders.mdx index dfdfbee9c..f58360b6f 100644 --- a/enterprise-api/bookmarks/get-bookmark-folders.mdx +++ b/enterprise-api/bookmarks/get-bookmark-folders.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks/folders ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/bookmarks/get-bookmarks-by-folder-id.mdx b/enterprise-api/bookmarks/get-bookmarks-by-folder-id.mdx index 98c7e3b07..6f0d421f4 100644 --- a/enterprise-api/bookmarks/get-bookmarks-by-folder-id.mdx +++ b/enterprise-api/bookmarks/get-bookmarks-by-folder-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks/folders/{folder_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/bookmarks/get-bookmarks.mdx b/enterprise-api/bookmarks/get-bookmarks.mdx index fc3894243..e1367873c 100644 --- a/enterprise-api/bookmarks/get-bookmarks.mdx +++ b/enterprise-api/bookmarks/get-bookmarks.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/add-members-to-a-chat-group-conversation.mdx b/enterprise-api/chat/add-members-to-a-chat-group-conversation.mdx index f00d92fb1..8fb7a1c1e 100644 --- a/enterprise-api/chat/add-members-to-a-chat-group-conversation.mdx +++ b/enterprise-api/chat/add-members-to-a-chat-group-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/members ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/add-public-key.mdx b/enterprise-api/chat/add-public-key.mdx index 223225bec..e1e74153f 100644 --- a/enterprise-api/chat/add-public-key.mdx +++ b/enterprise-api/chat/add-public-key.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/public_keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/append-chat-media-upload.mdx b/enterprise-api/chat/append-chat-media-upload.mdx index 30258a57b..c39a26f0e 100644 --- a/enterprise-api/chat/append-chat-media-upload.mdx +++ b/enterprise-api/chat/append-chat-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/media/upload/{id}/append ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/create-chat-group-conversation.mdx b/enterprise-api/chat/create-chat-group-conversation.mdx index e6763a951..5c9da9d7d 100644 --- a/enterprise-api/chat/create-chat-group-conversation.mdx +++ b/enterprise-api/chat/create-chat-group-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/group ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/download-chat-media.mdx b/enterprise-api/chat/download-chat-media.mdx index 262e4eb51..87b77539b 100644 --- a/enterprise-api/chat/download-chat-media.mdx +++ b/enterprise-api/chat/download-chat-media.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/chat/media/{id}/{media_hash_key} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/finalize-chat-media-upload.mdx b/enterprise-api/chat/finalize-chat-media-upload.mdx index 266930c8d..e621e12e3 100644 --- a/enterprise-api/chat/finalize-chat-media-upload.mdx +++ b/enterprise-api/chat/finalize-chat-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/media/upload/{id}/finalize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/get-chat-conversation.mdx b/enterprise-api/chat/get-chat-conversation.mdx index 1e027d6c8..d9c722fc4 100644 --- a/enterprise-api/chat/get-chat-conversation.mdx +++ b/enterprise-api/chat/get-chat-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/chat/conversations/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/get-chat-conversations.mdx b/enterprise-api/chat/get-chat-conversations.mdx index a7a127f69..e40d59158 100644 --- a/enterprise-api/chat/get-chat-conversations.mdx +++ b/enterprise-api/chat/get-chat-conversations.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/chat/conversations ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/get-user-public-keys.mdx b/enterprise-api/chat/get-user-public-keys.mdx index 804e1cbc7..b20716f9a 100644 --- a/enterprise-api/chat/get-user-public-keys.mdx +++ b/enterprise-api/chat/get-user-public-keys.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/public_keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/initialize-chat-group.mdx b/enterprise-api/chat/initialize-chat-group.mdx index 6d33f4cd5..d2ce8cb39 100644 --- a/enterprise-api/chat/initialize-chat-group.mdx +++ b/enterprise-api/chat/initialize-chat-group.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/group/initialize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/initialize-chat-media-upload.mdx b/enterprise-api/chat/initialize-chat-media-upload.mdx index 763d9aca7..4dd0163ff 100644 --- a/enterprise-api/chat/initialize-chat-media-upload.mdx +++ b/enterprise-api/chat/initialize-chat-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/media/upload/initialize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/initialize-conversation-keys.mdx b/enterprise-api/chat/initialize-conversation-keys.mdx index 455ca4998..3da9a1a16 100644 --- a/enterprise-api/chat/initialize-conversation-keys.mdx +++ b/enterprise-api/chat/initialize-conversation-keys.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/mark-conversation-as-read.mdx b/enterprise-api/chat/mark-conversation-as-read.mdx index 40f028eb7..167bcec5f 100644 --- a/enterprise-api/chat/mark-conversation-as-read.mdx +++ b/enterprise-api/chat/mark-conversation-as-read.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/read ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/send-chat-message.mdx b/enterprise-api/chat/send-chat-message.mdx index b5c2693a1..54bae281f 100644 --- a/enterprise-api/chat/send-chat-message.mdx +++ b/enterprise-api/chat/send-chat-message.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/messages ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/chat/send-typing-indicator.mdx b/enterprise-api/chat/send-typing-indicator.mdx index 79b77242f..905dc52be 100644 --- a/enterprise-api/chat/send-typing-indicator.mdx +++ b/enterprise-api/chat/send-typing-indicator.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/typing ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/communities/get-community-by-id.mdx b/enterprise-api/communities/get-community-by-id.mdx index 2670fff6d..6644a4ed9 100644 --- a/enterprise-api/communities/get-community-by-id.mdx +++ b/enterprise-api/communities/get-community-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/communities/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/communities/search-communities.mdx b/enterprise-api/communities/search-communities.mdx index 28faf05a7..1e3761464 100644 --- a/enterprise-api/communities/search-communities.mdx +++ b/enterprise-api/communities/search-communities.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/communities/search ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/community-notes/create-a-community-note.mdx b/enterprise-api/community-notes/create-a-community-note.mdx index 09a19080d..787a19c20 100644 --- a/enterprise-api/community-notes/create-a-community-note.mdx +++ b/enterprise-api/community-notes/create-a-community-note.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/notes ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/community-notes/delete-a-community-note.mdx b/enterprise-api/community-notes/delete-a-community-note.mdx index 847876e9f..1594a3d0f 100644 --- a/enterprise-api/community-notes/delete-a-community-note.mdx +++ b/enterprise-api/community-notes/delete-a-community-note.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/notes/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/community-notes/evaluate-a-community-note.mdx b/enterprise-api/community-notes/evaluate-a-community-note.mdx index 547580179..b1c59ddc0 100644 --- a/enterprise-api/community-notes/evaluate-a-community-note.mdx +++ b/enterprise-api/community-notes/evaluate-a-community-note.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/evaluate_note ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/community-notes/introduction.mdx b/enterprise-api/community-notes/introduction.mdx index 5b3fbd4e7..e1e9962e4 100644 --- a/enterprise-api/community-notes/introduction.mdx +++ b/enterprise-api/community-notes/introduction.mdx @@ -1,6 +1,7 @@ --- keywords: ["Community Notes", "community notes API", "AI Note Writer", "fact checking", "notes API", "community notes search", "notes evaluation"] ---- + +description: The Community Notes Endpoints in the X API v2 allow developers to search for and propose Community Notes on X programmatically. Use of the API requires ...--- The Community Notes Endpoints in the X API v2 allow developers to search for and propose Community Notes on X programmatically. Use of the API requires your account being signed up for X Developer AI access and enrolled in Community Notes as an AI Note Writer. You can [enroll and learn more about AI Note Writers](https://communitynotes.x.com/guide/en/api/overview) in the Community Notes Guide. diff --git a/enterprise-api/community-notes/search-for-community-notes-written.mdx b/enterprise-api/community-notes/search-for-community-notes-written.mdx index 3a8680ef8..31ad6dce4 100644 --- a/enterprise-api/community-notes/search-for-community-notes-written.mdx +++ b/enterprise-api/community-notes/search-for-community-notes-written.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/notes/search/notes_written ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/community-notes/search-for-posts-eligible-for-community-notes.mdx b/enterprise-api/community-notes/search-for-posts-eligible-for-community-notes.mdx index d94faf9fa..07bd2628b 100644 --- a/enterprise-api/community-notes/search-for-posts-eligible-for-community-notes.mdx +++ b/enterprise-api/community-notes/search-for-posts-eligible-for-community-notes.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/notes/search/posts_eligible_for_notes ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/compliance/batch-compliance/integrate.mdx b/enterprise-api/compliance/batch-compliance/integrate.mdx index b23d32400..bdee60666 100644 --- a/enterprise-api/compliance/batch-compliance/integrate.mdx +++ b/enterprise-api/compliance/batch-compliance/integrate.mdx @@ -2,8 +2,9 @@ title: Integration guide sidebarTitle: Integration guide keywords: ["batch compliance integration", "compliance batch integration", "compliance jobs integration", "batch compliance setup"] ---- + +--- import { Button } from '/snippets/button.mdx'; ## Working with resumable uploads @@ -24,199 +25,4 @@ First, you will have to create a compliance job and specify whether you will be curl --request POST \ 'https://api.x.com/2/compliance/jobs' --header 'Authorization: Bearer $APP_ACCESS_TOKEN --header 'Content-Type: application/json' --data-raw '{ "type": "tweets", - "resumable": true -}' -``` - -If your API call is successful, you will get a response similar to the following: - -``` -{ - "data": { - "download_expires_at": "2021-08-18T19:42:55.000Z", - "status": "created", - "upload_url": "https://storage.googleapis.com/twttr-tweet-compliance/1425543269983784962/submission/1202726487847104512_1425543269983784962?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=complianceapi-public-svc-acct%40twttr-compliance-public-prod.iam.gserviceaccount.com%2F20210811%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210811T194255Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=355e4c4739ae508304d3df15b4e13e64b6c7752d8d79d73676a4d8e60dc5241f83924ad2a1f8b7bddcc768062bb9c64d39b8e8f7cce7f66ffbea9f9ed33a4da975b3a2c127fb738c1c1ff3c3964bd4d9dc0706e6c8a70e67522160ea774e090d2793e06f890d1158ce86be3031c1c471b74f961b6f18743a28730611000336286ad0111b41fb5d14aa813ff00cf06b3572dc68d0b3c6fdc07f25c1b1196c1af4325a9ead68994944bbef0d2123585ea051deb9765aa7f5832446440bc9ba76af327b69df1fd7b1a99bd4419c128f1f697dbbacbc62bbc7c2c9aebc82a2128be0ed05d48a54d814162daad1232a0d13081e9543ab8557f567149af82281193f37", - "created_at": "2021-08-11T19:42:55.000Z", - "resumable": false, - "id": "1425543269983784962", - "type": "tweets", - "download_url": "https://storage.googleapis.com/twttr-tweet-compliance/1425543269983784962/delivery/1202726487847104512_1425543269983784962?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=complianceapi-public-svc-acct%40twttr-compliance-public-prod.iam.gserviceaccount.com%2F20210811%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210811T194255Z&X-Goog-Expires=604800&X-Goog-SignedHeaders=host&X-Goog-Signature=0a11dd5a3c5adb508f32ce904568abada863dc9499ba2adeafb3452ccee0dcb3dade17910dbc502dcbe54c130ac4d8638eb176c8b7344de068139b06c970794efa6312f0a5149f40da441eafcaf475f670c93ca73951999902a531d34dfab1e5490918929e5b06ae803b5604e0c0c26852255ccdbc79a2c1e2eefe924e5e6bf5b6603a7f287d1621333b9548ec6cc203716070528bebc2e67c12e92b1f4e54471db92c15a54799f2b855ae224250ca44c47993fd7d79a4940a0f68fe09f73fc8b291e88cfd10ade860b4b35c2b964d1777c1d93cd300c313138d9ca90aa8b3ecd3bf9dc73d3ebe32ba7634228fe07e1e4ecdda57cd94c802afc520162735d5a3", - "upload_expires_at": "2021-08-11T19:57:55.000Z" - } -} -``` - - -Take note of the value from the upload_url, you will need it in the following steps. - -#### Step two:  - -Next, you will need to initiate the resumable upload. In order to do so, make a **POST** call to the upload_url from the previous step and make sure to include the following headers: - -Content-Type: text/plain - -Content-Length: 0 - -x-goog-resumable: start - -``` -curl --request POST \ -'https://storage.googleapis.com/twttr-tweet-compliance/1430227686685757442/submission/1202726487847104512_1430227686685757442?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=complianceapi-public-svc-acct%40twttr-compliance-public-prod.iam.gserviceaccount.com%2F20210824%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210824T175707Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-length%3Bcontent-type%3Bhost%3Bx-goog-resumable&X-Goog-Signature=890d958f9c7dcb7f238e4971b59da5afc5b8329fb197c67b5930fe0f9dfe180afe2d4bec341111809b88ccfab46ab1f81f4242abc1af7b67c6e8977c52e6d486f5f43ce6a37a7a6530d25f15e2bcd9bb54655fe4ee22b26f8886ba71b67b7b11afd1198d658d1b6f0c41260f55260a260e1be0239977feba43dce40bc0e8e6293a4a3a3f7ee0afc74d3d2f7f2d3d514f108d5887a52ac85760385e5b9bb67cd26bfcf6b1c19151ea8111e217a29407722dc0dc9ab373334e88c18159546237ec9334f9a1e33717dc82800c6a45bba82706d5aece84ecdf3fcac52b21c8a3085a639047cf2707a8b9e4c296fc7cf05edbb110f07b89e38f0f5ea77e8b313cade7' \ ---header 'Content-Type: text/plain' --header \ - 'Content-Length: 0' --header \ - 'x-goog-resumable: start - ``` - - -If this call is successful, you will get a 201 response code. Then, in the response header, copy the value for the location header which will look something like this: - -``` -https://storage.googleapis.com/twttr-tweet-compliance/1430227686685757442/submission/1202726487847104512_1430227686685757442?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=complianceapi-public-svc-acct%40twttr-compliance-public-prod.iam.gserviceaccount.com%2F20210824%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210824T175707Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-length%3Bcontent-type%3Bhost%3Bx-goog-resumable&X-Goog-Signature=890d958f9c7dcb7f238e4971b59da5afc5b8329fb197c67b5930fe0f9dfe180afe2d4bec341111809b88ccfab46ab1f81f4242abc1af7b67c6e8977c52e6d486f5f43ce6a37a7a6530d25f15e2bcd9bb54655fe4ee22b26f8886ba71b67b7b11afd1198d658d1b6f0c41260f55260a260e1be0239977feba43dce40bc0e8e6293a4a3a3f7ee0afc74d3d2f7f2d3d514f108d5887a52ac85760385e5b9bb67cd26bfcf6b1c19151ea8111e217a29407722dc0dc9ab373334e88c18159546237ec9334f9a1e33717dc82800c6a45bba82706d5aece84ecdf3fcac52b21c8a3085a639047cf2707a8b9e4c296fc7cf05edbb110f07b89e38f0f5ea77e8b313cade7&upload_id=ADPycds-_Ow7aqcpbG4XguXSVAgd_2fy-XiDA2qm-It9PCwBlZhF4e2bfOAQzEmRJ4T_l6jU6LfYdfrKa_KlFFBOyx3PjYzrxQ -``` - - -You can then upload your Post or User IDs to this location by following step two onwards, [from the quick start guide](/x-api/compliance/batch-compliance#getting-started-with-the-batch-compliance-endpoints). - - -Because of their technical complexity, resumable uploads are best used in conjunction with code. This guide will use Node.js with the [needle request library](https://www.npmjs.com/package/needle). - -### Install the dependencies - -Before proceeding, you should have a Node.js environment installed; you can obtain Node.js from its website. Once installed, Node.js will contain a utility called npm; make sure both Node and npm are installed by calling the following command, and ensure it doesn’t result in an error. - - `$ npm -v -6.4.1` - -A version number similar to this signifies your environment is ready (note that your version number may differ). We will use npm to install the upload library. Run this command: - - `$ npm install -g needle` - -You’re all set; there is no additional configuration required. - -#### Request a resumable destination - -When creating a new job, set the resumable parameter to true so you can get a destination that supports a resumable upload. In the response payload, you will receive an upload_url value. - -``` -"upload_url":\ -"https://storage.googleapis.com/compliance_tweet_ids/customer_test_object_12950882_GlYjiE?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=193969463581-compute%40developer.gserviceaccount.com%2F20200618%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200618T184154Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=b7bdcf32479b08715be91ed47b06471b8acdcdb319f8e4f423bf3a3056dfa03ed83e47446f33338e292967a15c08fa5ba34395edaf057a2ac975b88e710ca994adb023a9e1673a7c58ce2fa0d73537f72812af78e92b708dfe6b907a7d75bd0f6cfa61fec867e80ac83ced0725d1ee59787c9dbca50d41f7b0f513dad63a7564136b1a70042a2ec6ba6b697cbe480a4405362f7a08255a5e8205aa7baa562f99e6a092f0420f33d67ffaeb132f877fbaf16c969630b5f173e8a3f31c473707241fa4e28f4bed13fb2ea01d3af1c449321a2e6ee9ec1e331b447cabcfc6f9d1f99f564d180f0cc1d28ea54972c996102c67c6501c6c16a00c13d17756f960e0e1" -``` - -#### Prepare the code to upload a file - -By default, the library will create a new upload destination by accepting an upload location (called bucket) and the name of the file you wish to upload. Because the batch compliance endpoints create their own destination, we will need to tell the library we already have a location ready to accept our upload.  - - -We will need to pass this value to the upload library, along with the name of the file containing the data to upload. Create a file, and name it _**twitter-upload.js**_. Add the following code: - -``` -const needle = require('needle'); -const fs = require('fs'); -const path = require('path'); - -const [, scriptName, filename, uploadURL] = process.argv; -if (!filename || !uploadURL) { - console.error(`Usage: node ${path.basename(scriptName)} filename upload_url`); - process.exit(-1); -} - -async function uploadFile(file, url) { - // rangeEnd is the index of the last byte in the file, i.e. number of bytes in file - const rangeEnd = (await fs.promises.stat(file)).size; - - let options = { - headers: { - 'Content-Range': `bytes */${rangeEnd}`, - }, - }; - - const response = await needle('put', url, null, options); - - switch (response.statusCode) { - case 200: - case 201: - console.log('Upload complete'); - return; - case 308: - return resumeUpload(response, file, url); - default: - console.log('Got unexpected response code: ', response.statusCode); - return; - } -} - -async function resumeUpload(response, file, url) { - console.log('Upload not completed, resuming'); - if (response.headers.range) { - let resumeOffset = Number(response.headers.range.split('-')[1]) + 1; - - let options = { - headers: { - 'Content-Range': `bytes ${resumeOffset}-${rangeEnd-1}/${rangeEnd}`, - 'Content-Length': `${rangeEnd-resumeOffset}`, - }, - }; - - let readStream = fs.createReadStream(file, {start: resumeOffset}); - return needle('put', url, readStream, options); - } else { - console.log('Initiating upload'); - let options = { - headers: { - 'Content-Type': 'text/plain' - } - }; - - let readStream = fs.createReadStream(file); - return needle('put', url, readStream, options); - } -} - -// Request resumable session URL -async function requestResumableSession(url) { - const options = { - headers: { - 'Content-Type': 'text/plain', - 'Content-Length': '0', - 'x-goog-resumable': 'start', - }, - }; - - const res = await needle('post', url, null, options); - if (res.statusCode === 201) { - const resumableSessionURL = res.headers['location']; - console.log('Starting upload to: ', resumableSessionURL); - - await uploadFile(filename, resumableSessionURL); - } else { - console.log('Failed to create resumable session URI'); - } - -} - -requestResumableSession(uploadURL).then(result => console.log('Upload complete')); -``` - -Save the file wherever it makes the most sense. Next, in your command line, invoke the script and pass two parameters: - -1. The first will be the location of the file (with the Post or User IDs) that you wish to upload. -2. The second will be the upload URL we received from the compliance endpoint response. - -Ensure the URL is surrounded in double-quotes, and do the same for your file name if it contains spaces or other characters: - -``` -node twitter-upload.js compliance_upload.txt\ -"https://storage.googleapis.com/compliance_tweet_ids/customer_test_object_12950882_GlYjiE?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=193969463581-compute%40developer.gserviceaccount.com%2F20200618%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200618T184154Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=b7bdcf32479b08715be91ed47b06471b8acdcdb319f8e4f423bf3a3056dfa03ed83e47446f33338e292967a15c08fa5ba34395edaf057a2ac975b88e710ca994adb023a9e1673a7c58ce2fa0d73537f72812af78e92b708dfe6b907a7d75bd0f6cfa61fec867e80ac83ced0725d1ee59787c9dbca50d41f7b0f513dad63a7564136b1a70042a2ec6ba6b697cbe480a4405362f7a08255a5e8205aa7baa562f99e6a092f0420f33d67ffaeb132f877fbaf16c969630b5f173e8a3f31c473707241fa4e28f4bed13fb2ea01d3af1c449321a2e6ee9ec1e331b447cabcfc6f9d1f99f564d180f0cc1d28ea54972c996102c67c6501c6c16a00c13d17756f960e0e1" -``` - -You will see output similar to this: - - `Starting upload to: https://storage.googleapis.com/twttr-tweet-compliance/ -Upload not completed, resuming -Initiating upload` - -You can pause the upload at any time by pressing Ctrl + C or closing your command line. You will be able to resume the upload from where you left off when you invoke the same command at a later stage. Once the file has been completely uploaded, you will see the following message: - - `Upload complete` - -At this point, you will be able to use the [compliance status endpoint](/x-api/compliance/get-compliance-job) to check on the status of your compliance job, and you will be able to download the compliance result when complete. + \ No newline at end of file diff --git a/enterprise-api/compliance/create-compliance-job.mdx b/enterprise-api/compliance/create-compliance-job.mdx index 84dfc45d1..e72c0270d 100644 --- a/enterprise-api/compliance/create-compliance-job.mdx +++ b/enterprise-api/compliance/create-compliance-job.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/compliance/jobs ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/compliance/get-compliance-job-by-id.mdx b/enterprise-api/compliance/get-compliance-job-by-id.mdx index 57cc5c311..932937eba 100644 --- a/enterprise-api/compliance/get-compliance-job-by-id.mdx +++ b/enterprise-api/compliance/get-compliance-job-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/compliance/jobs/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/compliance/get-compliance-jobs.mdx b/enterprise-api/compliance/get-compliance-jobs.mdx index 95c296b56..ed9a9a62e 100644 --- a/enterprise-api/compliance/get-compliance-jobs.mdx +++ b/enterprise-api/compliance/get-compliance-jobs.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/compliance/jobs ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/connections/get-connection-history.mdx b/enterprise-api/connections/get-connection-history.mdx index fff3b9942..9f84e5246 100644 --- a/enterprise-api/connections/get-connection-history.mdx +++ b/enterprise-api/connections/get-connection-history.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/connections ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/connections/terminate-all-connections.mdx b/enterprise-api/connections/terminate-all-connections.mdx index 6f4499329..eec4847be 100644 --- a/enterprise-api/connections/terminate-all-connections.mdx +++ b/enterprise-api/connections/terminate-all-connections.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/connections/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/connections/terminate-connections-by-endpoint.mdx b/enterprise-api/connections/terminate-connections-by-endpoint.mdx index 3b36dadfc..1373898d3 100644 --- a/enterprise-api/connections/terminate-connections-by-endpoint.mdx +++ b/enterprise-api/connections/terminate-connections-by-endpoint.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/connections/{endpoint_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/connections/terminate-multiple-connections.mdx b/enterprise-api/connections/terminate-multiple-connections.mdx index 5e2e0e1a2..fbc61eb40 100644 --- a/enterprise-api/connections/terminate-multiple-connections.mdx +++ b/enterprise-api/connections/terminate-multiple-connections.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/connections ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/blocks/introduction.mdx b/enterprise-api/direct-messages/blocks/introduction.mdx index d682a957b..1f8f7e053 100644 --- a/enterprise-api/direct-messages/blocks/introduction.mdx +++ b/enterprise-api/direct-messages/blocks/introduction.mdx @@ -1,65 +1,66 @@ ---- -title: Introduction -sidebarTitle: Introduction -keywords: ["DM blocks", "direct message blocks", "block DMs", "DM blocking", "direct message blocking", "block messages"] ---- - -The manage DM blocks endpoints enable you to block or unblock a specified account on behalf of an authenticated user. For these endpoints, there are two POST methods available: - -* **/2/users/:id/dm/block**: Allows you to block an account -* **/2/users/:id/dm/unblock**: Allows you to unblock an account - - -### Getting started -### Authentication - -Since you are making requests on behalf of a user, you must authenticate these endpoints with either [OAuth 1.0a User Context](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) or [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2), and utilize the user Access Tokens associated with the user you are making the request on behalf of. You can generate this user Access Token using the [3-legged OAuth flow](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens) (OAuth 1.0a) or using the [Authorization Code with PKCE grant flow](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) (OAuth 2.0). - -### Making a request - -Block - -Once a user has authenticated with your app, you can call the Block endpoint on behalf of user as shown below: - - ``` - curl --request POST 'https://api.x.com/2/users/:id/dm/block' --header 'Authorization: ••••••' - ``` - - - - -If the request is successful, you should see the JSON response as shown below: - -``` -{ - "data": { - "blocked": true - } -} -``` - - - - -**Unblock** - -Once a user has authenticated with your app, you can call the Unblock endpoint on behalf of user as shown below: - - ``` - curl --request POST 'https://api.x.com/2/users/:id/dm/unblock' --header 'Authorization: ••••••' - ``` - - - - -If the request is successful, you should see the JSON response as shown below: - -``` -{ - "data": { - "blocked": false - } -} -``` - - +--- +title: Introduction +sidebarTitle: Introduction +keywords: ["DM blocks", "direct message blocks", "block DMs", "DM blocking", "direct message blocking", "block messages"] + +description: The manage DM blocks endpoints enable you to block or unblock a specified account on behalf of an authenticated user. For these endpoints, there are two...--- + +The manage DM blocks endpoints enable you to block or unblock a specified account on behalf of an authenticated user. For these endpoints, there are two POST methods available: + +* **/2/users/:id/dm/block**: Allows you to block an account +* **/2/users/:id/dm/unblock**: Allows you to unblock an account + + +### Getting started +### Authentication + +Since you are making requests on behalf of a user, you must authenticate these endpoints with either [OAuth 1.0a User Context](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) or [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2), and utilize the user Access Tokens associated with the user you are making the request on behalf of. You can generate this user Access Token using the [3-legged OAuth flow](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens) (OAuth 1.0a) or using the [Authorization Code with PKCE grant flow](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) (OAuth 2.0). + +### Making a request + +Block + +Once a user has authenticated with your app, you can call the Block endpoint on behalf of user as shown below: + + ``` + curl --request POST 'https://api.x.com/2/users/:id/dm/block' --header 'Authorization: ••••••' + ``` + + + + +If the request is successful, you should see the JSON response as shown below: + +``` +{ + "data": { + "blocked": true + } +} +``` + + + + +**Unblock** + +Once a user has authenticated with your app, you can call the Unblock endpoint on behalf of user as shown below: + + ``` + curl --request POST 'https://api.x.com/2/users/:id/dm/unblock' --header 'Authorization: ••••••' + ``` + + + + +If the request is successful, you should see the JSON response as shown below: + +``` +{ + "data": { + "blocked": false + } +} +``` + + diff --git a/enterprise-api/direct-messages/create-dm-conversation.mdx b/enterprise-api/direct-messages/create-dm-conversation.mdx index d6c7dbf87..b02c04808 100644 --- a/enterprise-api/direct-messages/create-dm-conversation.mdx +++ b/enterprise-api/direct-messages/create-dm-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/dm_conversations ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/create-dm-message-by-conversation-id.mdx b/enterprise-api/direct-messages/create-dm-message-by-conversation-id.mdx index 956387ec1..7d3fbc1ec 100644 --- a/enterprise-api/direct-messages/create-dm-message-by-conversation-id.mdx +++ b/enterprise-api/direct-messages/create-dm-message-by-conversation-id.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/dm_conversations/{dm_conversation_id}/messages ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/create-dm-message-by-participant-id.mdx b/enterprise-api/direct-messages/create-dm-message-by-participant-id.mdx index 4e9eb0f24..46318b3fe 100644 --- a/enterprise-api/direct-messages/create-dm-message-by-participant-id.mdx +++ b/enterprise-api/direct-messages/create-dm-message-by-participant-id.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/dm_conversations/with/{participant_id}/messages ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/delete-dm-event.mdx b/enterprise-api/direct-messages/delete-dm-event.mdx index 14a42696f..a5bdbd851 100644 --- a/enterprise-api/direct-messages/delete-dm-event.mdx +++ b/enterprise-api/direct-messages/delete-dm-event.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/dm_events/{event_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/download-dm-media.mdx b/enterprise-api/direct-messages/download-dm-media.mdx index 41739778e..074469121 100644 --- a/enterprise-api/direct-messages/download-dm-media.mdx +++ b/enterprise-api/direct-messages/download-dm-media.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_conversations/media/{dm_id}/{media_id}/{resource_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/get-dm-event-by-id.mdx b/enterprise-api/direct-messages/get-dm-event-by-id.mdx index 03b648cf1..fd48fa1f2 100644 --- a/enterprise-api/direct-messages/get-dm-event-by-id.mdx +++ b/enterprise-api/direct-messages/get-dm-event-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_events/{event_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation-1.mdx b/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation-1.mdx index bcd2d6dd0..420a6b94f 100644 --- a/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation-1.mdx +++ b/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation-1.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_conversations/{id}/dm_events ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation.mdx b/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation.mdx index 37c967c67..d86382fe4 100644 --- a/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation.mdx +++ b/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_conversations/with/{participant_id}/dm_events ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/get-dm-events.mdx b/enterprise-api/direct-messages/get-dm-events.mdx index 89969dc9b..2b1eb0e0f 100644 --- a/enterprise-api/direct-messages/get-dm-events.mdx +++ b/enterprise-api/direct-messages/get-dm-events.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_events ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/direct-messages/lookup/integrate.mdx b/enterprise-api/direct-messages/lookup/integrate.mdx index ec19ae25d..377258c11 100644 --- a/enterprise-api/direct-messages/lookup/integrate.mdx +++ b/enterprise-api/direct-messages/lookup/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating DM lookup endpoints keywords: ["direct messages integration", "DM integration", "DM lookup integration"] --- diff --git a/enterprise-api/direct-messages/lookup/migrate.mdx b/enterprise-api/direct-messages/lookup/migrate.mdx index 1cd190226..1c895394a 100644 --- a/enterprise-api/direct-messages/lookup/migrate.mdx +++ b/enterprise-api/direct-messages/lookup/migrate.mdx @@ -2,7 +2,8 @@ title: Migration guide sidebarTitle: Migration guide keywords: ["direct messages migration", "DM migration", "v1.1 to v2 DM lookup", "DM migration guide", "migrate DM lookup"] ---- + +description: 1 and v2 versions of the Direct Messages endpoints provide methods for looking up Direct Message events.--- import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/direct-messages/manage/integrate.mdx b/enterprise-api/direct-messages/manage/integrate.mdx index 3ddec077e..cac4e9761 100644 --- a/enterprise-api/direct-messages/manage/integrate.mdx +++ b/enterprise-api/direct-messages/manage/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for sending Direct Messages keywords: ["manage direct messages integration", "DM management integration", "send DM integration"] --- diff --git a/enterprise-api/direct-messages/manage/migrate.mdx b/enterprise-api/direct-messages/manage/migrate.mdx index 5e22406e0..28851ea49 100644 --- a/enterprise-api/direct-messages/manage/migrate.mdx +++ b/enterprise-api/direct-messages/manage/migrate.mdx @@ -2,7 +2,8 @@ title: Migration guide sidebarTitle: Migration guide keywords: ["manage direct messages migration", "DM management migration", "v1.1 to v2 manage DMs", "DM migration guide", "migrate DM management"] ---- + +description: 1 and v2 versions of the Direct Messages endpoints provide methods for creating Direct Message messages.--- import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/enterprise-gnip-2.0/enterprise-gnip.mdx b/enterprise-api/enterprise-gnip-2.0/enterprise-gnip.mdx deleted file mode 100644 index 7a1f2aedd..000000000 --- a/enterprise-api/enterprise-gnip-2.0/enterprise-gnip.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Enterprise -keywords: ["enterprise API", "GNIP", "enterprise data", "enterprise access", "enterprise API", "GNIP API", "enterprise"] ---- - -import { Button } from '/snippets/button.mdx'; - - -Our enterprise APIs offer the highest level of access and reliability to those who depend on X data. Perfect as you scale beyond premium and need more reliable access, custom tailored packages, or longer-term contracts. Enterprise API access comes with dedicated account managers and personalized technical support. - -If you’ve identified that the Basic and Pro solutions aren’t enough to support your needs, you can apply for access to the enterprise products at the following link: - - - -## Available endpoints - -| Real-time | [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api) | Provides complete coverage of public Posts as they happen, filterable using a wide range of operators and rules. | -| :--- | :--- | :--- | -| [Decahose API](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api) | Stream a random sample of 10% of all public Posts and their likes. | -| :--- | :--- | :--- | -| [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) | Subscribe to users and receive a variety of different activities including Posts, Direct Messages, likes, follows, and more. | -| :--- | :--- | :--- | -| Historical | [Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api) | Search either the previous 30 days or the full archive of public Posts using advanced filtering tools. | -| [Historical PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api) | Filter the full archive of public Posts using an economical batch access process. | -| Insights | [Engagement API](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api) | Measure the volume of impressions and engagements for public Posts. | -| Compliance | [Compliance Firehose API](/x-api/enterprise-gnip-2.0/fundamentals/firehouse) | Stream all compliance events. | -| Usage | [Usage API](/x-api/enterprise-gnip-2.0/fundamentals/usage) | Provides programmatic access to activity consumption across enterprise products. | - -## Important concepts - -### Gnip Console - -You can manage your enterprise products and account access via the [Gnip Console](/x-api/enterprise-gnip-2.0/fundamentals/overview).  - - -### Enrichments - -We’ve added metadata to the response payload of the premium APIs for developers who are using a paid tier. Learn more about expanded URLs, poll data, and profile geo by visiting our [enrichments section](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments). -  - -### Advanced filtering tools - -The Premium Search API makes available an advanced set of operators that are not available with the standard search endpoint. Many of these operators are available to the free sandbox users, but you will get a more robust set of operators if you are using a paid tier. Learn more by visiting our [rules and filters section](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#getting-started-with-enterprise-rules-and-queries). - -## Explore X API v2 - -Interested in exploring what's available now in v2? Check out our documentation to see what's new, and visit the migration hub for resources that will help you eventually move to the X API v2. You can also access migration guides for each endpoint listed in the new v2 endpoint sections. - -[Learn more](/x-api/migrate/overview) - -Need help? - -Check out our support section or reach out to your account manager to learn how you can get in contact with our support team. - -[Support](https://developer.x.com/en/support/x-api)) diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/account-activity.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/account-activity.mdx deleted file mode 100644 index 44b37975c..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/account-activity.mdx +++ /dev/null @@ -1,2114 +0,0 @@ ---- -title: "Account Activity API: Enterprise" -keywords: ["enterprise Account Activity API", "enterprise AAA", "Account Activity enterprise", "enterprise webhooks", "enterprise activity"] ---- - -This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the ["Edit Posts" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets).  - -This endpoint is often used with the Direct Messages endpoints. We have launched new [v2 Direct Messages endpoints](/x-api/direct-messages/manage/introduction). Note that the Enterprise and Premium Account Activity APIs support v2 one-to-one messages, but do not yet support group conversations.    - -Overview - -`Enterprise` - -The Account Activity API provides you the ability to subscribe to realtime activities related to a user account via webhooks. This means that you can receive realtime Posts, Direct Messages, and other account events from one or more of your owned or subscribed accounts through a single connection. - -You will receive all related activities below for each user subscription on your webhook registration: - -| Activity types | | -| :--- | :--- | -| * Posts (by user)

* Post deletes (by user)
* @mentions (of user)
* Replies (to or from user)
* Retweets (by user or of user)
* Quote Tweets (by user or of user)
* Retweets of Quoted Tweets (by user or of user)
* Likes (by user or of user)
* Follows (by user or of user)

* Unfollows (by user) | * Blocks (by user)
* Unblocks (by user)
* Mutes (by user)
* Unmutes (by user)
* Direct Messages sent (by user)
* Direct Messages received (by user)
* Typing indicators (to user)
* Read receipts (to user)
* Subscription revokes (by user) | - -**Please note** \- We do not deliver home timeline data via the Account Activity API. Please use the [GET statuses/home_timeline](https://developer.x.com/en/docs/x-api/v1/tweets/timelines/overview) to pull this data. -  - -#### Video Series - -Check out our [four-part video series](https://www.youtube.com/watch?v=otPxejFhyy8&index=0&list=PLFKjcMIU2WshGG6Yj940XM7Z6BFs1zfBg) on the Account Activity API to get up to speed! - - -### Feature summary - -| Tier | Pricing | Number of unique subscriptions | Number of webhooks | Reliability and Activity Recovery | -| :--- | :--- | :--- | :--- | :--- | -| Enterprise | [Contact sales](/x-api/enterprise-gnip-2.0/enterprise-gnip) | Up to 500+ | 3+ | [Retries](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#retries) and [Replay](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-replay-api) | - - - -* Have questions? Running into errors? - * Read our [Frequently asked questions](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#frequently-asked-questions) or [Error Troubleshooting guide](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#frequently-asked-questions). - - -* Explore our sample code: - * [Enterprise Account Activity API dashboard](https://github.com/xdevplatform/account-activity-dashboard-enterprise), a node web app that displays webhook events using the enterprise tier of the Account Activity API and includes [Replay](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-replay-api) functionality. - * The [SnowBot chatbot](https://github.com/xdevplatform/SnowBotDev), a Ruby web app built on the enterprise Account Activity and Direct Message APIs. - -## Manage webhooks and subscribed users - -**⏱ 10 min read** - -The enterprise Account Activity API provides you webhook-based JSON messages any time there are events associated with X accounts subscribed to your service. X delivers those activities to your registered webhook. In the following steps, you will learn how to manage webhooks and subscribed users. - -You will learn how to register, view, and remove, both webhooks and subscribed users. We'll be using simple cURL commands to make requests to the various API endpoints. cURL is a command-line tool for getting or sending requests using the URL syntax. - -You will need: - -* A registered X app - _[register here](https://developer.x.com/content/developer-twitter/en/apps)_ -* A bearer token - _[learn more](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token)_ -* A webhook that passes a Challenge-Response Check (CRC) - _[learn more](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#securing-webhooks)_ -* An enterprise account - _[apply here]https://developer.x.com/en/products/x-api/enterprise_ - -_Before you get started, we recommend you check out our [Github repo here](https://github.com/xdevplatform/account-activity-dashboard) that provides a sample web app and helper scripts to get started with X's Account Activity API_ - -#### Managing a webhook: - - -Using a webhook provides you the ability to subscribe to realtime activities related to a user account through a single connection.  - - -Let’s begin with registering a new webhook URL for the given application context. - -The URL will be validated via a CRC request before saving. Once you've registered a webhook, make sure to document the webhook ID as you will need it later on. - -Copy the following cURL request into your command line after making changes to the following: - -* **URL** `` e.g. `https://yourdomain.com/webhooks/twitter/` - -* **Consumer key** `` e.g. `xvz1evFS4wEEPTGEFPHBog` - -* **Access token** `` e.g.  `370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb` - - ``` - curl --request POST --url 'https://api.x.com/1.1/account_activity/webhooks.json?url=' --header 'authorization: OAuth oauth_consumer_key="", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="", oauth_version="1.0"' - ``` - - -We will run the following command to returns all registered webhook URLs and their statuses for the given application. - -Copy the following cURL request into your command line after making changes to the following: - -* **Bearer token** `` e.g. `AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...` - - ```curl --request GET --url https://api.x.com/1.1/account_activity/webhooks.json --header 'authorization: Bearer ' - ``` - - -To remove a webhook from the provided application's configuration, copy the following cURL request into your command line after making changes to the following: - -* **Webhook ID** `<:WEBHOOK_ID>` e.g. `1234567890` - -* **Consumer key** `` e.g. `xvz1evFS4wEEPTGEFPHBog` - -* **Access token** `` e.g.  `370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb` - - ```curl --request DELETE --url https://api.x.com/1.1/account_activity/webhooks/<:WEBHOOK_ID>.json --header 'authorization: OAuth oauth_consumer_key="", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="", oauth_version="1.0"' - ``` - - - -#### Managing subscribed users: - - -Once you've registered a Webhook, you can add a subscribed user to the Account Activity API to begin receiving their account activities. - - -We'll begin with subscribing a user so you recieve all event types. - -Copy the following cURL request into your command line after making changes to the following: - -* **Webhook ID** `<:WEBHOOK_ID>` e.g. `1234567890` - -* **Consumer key name** `` e.g. `xvz1evFS4wEEPTGEFPHBog` - -* **Subscribing user's access token** `` e.g. `370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb` - - - ``` - curl --request POST --url https://api.x.com/1.1/account_activity/webhooks/<:WEBHOOK_ID>/subscriptions/all.json --header 'authorization: OAuth oauth_consumer_key="", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="", oauth_version="1.0"' - ``` - - -To view a list of all activity type subscriptions for a specified webhook, copy the following cURL request into your command line after making changes to the following: - -* **Webhook ID** `<:WEBHOOK_ID>` e.g. `1234567890` - -* **Bearer token** `` e.g. `AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...` - - - ``` - curl --request GET --url https://api.x.com/1.1/account_activity/webhooks/<:WEBHOOK_ID>/subscriptions/all/list.json --header 'authorization: Bearer ' - ``` - - -After deactivation, all events for the requesting user will no longer be sent to the webhook URL. - -To deactivate a subscription from the provided user context and application, copy the following cURL request into your command line after making changes to the following: - -* **Webhook ID** `<:WEBHOOK_ID>` e.g. `1234567890` - -* **Consumer key** `` e.g. `xvz1evFS4wEEPTGEFPHBog` - -* **Subscribing user's access token** `` e.g. `370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb` - - - ``` - curl --request DELETE --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBED_USER'S_ACCESS_TOKEN", oauth_version="1.0"' - ``` - - - -Great job! You should now able to manage your webhooks and subscribed users. - -#### Referenced articles - -* [Overview of Challenge-Response Check (CRC)](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#securing-webhooks) -* [Account Activity Data Types](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-data-object-structure) -* [Managing Webhooks and Subscriptions](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#managing-webhooks-and-subscriptions) - - -## A video walkthrough of the Account Activity API - -In this video walkthrough, you will learn about the capabilities of the premium and enterprise tiers of the Account Activity API. - -By the end of this video, you will learn about the following capabilities. - -* Registering a webhook -* Adding a user subscription -* Removing a user subscription -* Receiving account activities -* Replay account activities - - - - -* Have questions? Running into errors? - * Read our [Frequently asked questions](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#frequently-asked-questions) or [Error Troubleshooting guide](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#frequently-asked-questions). - - -* Explore our sample code: - * [Enterprise Account Activity API dashboard](https://github.com/xdevplatform/account-activity-dashboard-enterprise), a node web app that displays webhook events using the enterprise tier of the Account Activity API and includes [Replay](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-replay-api) functionality. - * The [SnowBot chatbot](https://github.com/xdevplatform/SnowBotDev), a Ruby web app built on the enterprise Account Activity and Direct Message APIs. - -**Enterprise** - -## Getting started with webhooks - -The Account Activity API is a webhook-based API that sends account events to a web app you develop, deploy and host.  - -There are several 'plumbing' details that need attention before you can start receiving webhook events in your event consumer application. As described below, you will need to create a X app, obtain Account Activity API access, and develop a web app that consumes webhook events.  - -### 1\. Create a X app. - -* Create a [X app](/resources/fundamentals/developer-apps) with an approved developer account from the [Developer Console](/resources/fundamentals/developer-portal). If you are creating the app on behalf of your company, it is recommended you create the app with a corporate X account. To apply for a developer account, [click here](/resources/fundamentals/developer-apps). -* Enable “Read, Write and Access direct messages” on the [permissions](/resources/fundamentals/developer-apps#oauth-1-0a-app-permissions) tab of your app page. -* On the "Keys and Access Tokens" tab, take note of your app's Consumer Key (API Key) and Consumer Token (API Secret). -* On the same tab, generate your app's [Access Token and Access Token Secret](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). You will need these Access Tokens to register your webhook URL, which is where X will send account events. -* If you are unfamiliar with [X Sign-in](/resources/fundamentals/authentication#log-in-with-x) and how user contexts work with the X API review [Obtaining Access Tokens](https://dev.x.com/webhooks/access-tokens). As you add accounts for which to receive events, you will subscribe them using that account's access tokens. -* Take note of your app's numeric ID, as seen in the ["Apps"](/resources/fundamentals/developer-apps) page of the [Developer Console](/resources/fundamentals/developer-portal). When you apply for Account Activity API access, you'll need this app ID. -   - -### 2\. Get Account Activity API access - -After creating a X app, the next step is applying for Account Activity API access.  - -Account Activity API is only availble on Enterprise, so you will need to submit an application using the link below. - - -### 3\. Develop webhook consumer app - -Once you have received Account Activity API access, you need to develop, deploy and host a web app that will receive X webhook events.  - -* Create a web app with a URL to use as your webhook to receive events. This is the endpoint deployed on your server to listen for incoming X webhook events.  - * The URI _path_ is completely up to you. This example would be valid: https://mydomain.com_/service/listen_ - - * If you are listening for webhooks from a variety of sources, a common pattern is: https://mydomain.com/webhook/twitter - * Note that the specified URL can not include a port specification (https://mydomain.com:5000/NoWorkie). -* As described in our [Securing Webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#securing-webhooks) guide, a first step is writing code that receives a X Challenge Response Check (CRC) GET request and responds with a properly formatted JSON response.  -* Register your webhook URL. You will make a POST request to a /webhooks.json?url= endpoint. When you make this request X will issue a CRC request to your web app. When a webhook is successfully registered, the response will include a webhook id. This webhook id is needed later when making some requests to the Account Activity API.  - -* X will send account webhook events to the URL you registered. Make sure your web app supports POST requests for incoming events. These events will be encoded in JSON. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-data-object-structure) for example webhook JSON payloads. -* Once your web app is ready, the next step is adding accounts to receive activities for. When adding (or deleting) accounts you will make POST requests referencing the account id. See our [guide on adding subscriptions](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#managing-webhooks-and-subscriptions) for more information. - - - -### 4\. Validate setup - -* To validate your app and webhook are configured correctly, favorite a Post posted by one of the X accounts your app is subscribed to. You should receive a `favorite_events` via a POST request to your webhook URL for each Favorite your subscribers receive. -* Note that it may take up to 10 seconds for events to start being delivered after a subscription has been added. - -**Important Notes** - -* When registering your webhook URL, your web app must authenticate with its consumer token and secret _and the app owner's user access token and secret_.  -* All incoming Direct Messages will be delivered via webhooks. All Direct Messages sent via [POST direct\_messages/events/new (message\_create)](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) will also be delivered via webhooks. This is so your web app can be aware of Direct Messages sent via a different client. -* Note that every webhook event includes a for\_user\_id user ID that indicates which subscription the event was delivered for. -* If you have two users using your web app for Direct Messages in the same conversation, your webhook will receive two duplicate events (one for each user). Your web app should account for this.  - -* If you have more than one web app sharing the same webhook URL and the same user mapped to each app, the same event will be sent to your webhook multiple times (once per web app). -* In some cases, your webhook may receive duplicate events. Your webhook app should be tolerant of this and dedupe by event ID. -* Do not expect Quick Reply response to directly follow a request. A user has the ability to ignore a Quick Reply request and may respond via traditional Direct Message. The user may also provide a Quick Reply response to a request they have not replied to earlier in the message thread. - - - -* See example code: - * [Enterprise Account Activity API dashboard](https://github.com/xdevplatform/account-activity-dashboard-enterprise), a node web app that displays webhook events using the enterprise tier of the Account Activity API and includes [Replay](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-replay-api) functionality. - - * The [SnowBot chatbot](https://github.com/xdevplatform/SnowBotDev), a Ruby web app built on the Account Activity and Direct Message APIs. This code base includes a [script](https://github.com/xdevplatform/SnowBotDev/wiki/Account-Activity-API-setup-script) to help set up Account Activity API webhooks. - - -## Securing webhooks - -X's webhook-based APIs provide two methods for confirming the security of your webhook server: - -1. The challenge-response checks enable X to confirm the ownership of the web app receiving webhook events.  -2. The signature header in each POST request enables you to confirm that X is the source of the incoming webhooks. -   - - -### Challenge-Response Checks  - -In order to verify that you are both the owner of the app and the webhook URL, X will perform a Challenge-Response Check (CRC), which is not to be confused with a cyclic redundancy check. When a CRC is sent, X will make a GET request of your web app with a ;_`crc_token`_ parameter. When that request is received, your web app needs to build an encrypted `response_token` based on the _`crc_token`_ parameter and your app's Consumer Secret (details below). The response_token must be encoded in JSON (see example below) and returned within three seconds. When successful, a webhook `id` will be returned.  - -A CRC will be sent when you register your webhook URL, so implementing your CRC response code is a fundamental first step. Once your webhook is established, X will trigger a CRC roughly every 24 hours from the last time we received a successful response. Your app can also trigger a CRC when needed by making a PUT request with your webhook `id`. Triggering a CRC is useful as you develop your webhook application, after deploying new code and restarting your service.  - -The _`crc_token`_ should be expected to change for each incoming CRC request and should be used as the message in the calculation, where your Consumer Secret is the key. - -In the event that the response is not posted within 3 seconds or becomes invalid, events will cease to be sent to the registered webhook. - -#### The CRC request will occur: - -* When a webhook URL is registered. -* Approximately _hourly_ to validate your webhook URL. -* You can manually trigger a CRC by making a PUT request. As you develop your webhook client, you should plan on manually triggering the CRC as you develop your CRC response.  -   - -#### Response requirements: - -* A base64 encoded HMAC SHA-256 hash created from the `crc_token` and your app Consumer Secret -* Valid response_token and JSON format. -* Latency less than 3 seconds. -* 200 HTTP response code. -   - -#### Language-specific HMAC libraries: - -* [Java/Scala](https://docs.oracle.com/javase/8/docs/api/index.html?javax/crypto/Mac.html) -* [Ruby](http://ruby-doc.org/stdlib-2.1.0/libdoc/openssl/rdoc/OpenSSL/HMAC.html) -* [Node.js](https://nodejs.org/api/crypto.html#crypto_class_hmac) -* [Python](https://docs.python.org/2/library/hmac.html) - -#### Example response token generation in Python: - -The following defines a route in a Python 2.7 Flask webapp that will respond to the challenge response check correctly. -``` -import base64 -import hashlib -import hmac -import json - - -\# Defines a route for the GET request -@app.route('/webhooks/twitter', methods=\['GET'\]) -def webhook_challenge(): - -  # creates HMAC SHA-256 hash from incomming token and your consumer secret -  sha256\_hash\_digest = hmac.new(TWITTER\_CONSUMER\_SECRET, msg=request.args.get('crc_token'), digestmod=hashlib.sha256).digest() - -  # construct response data with base64 encoded hash -  response = { -    'response\_token': 'sha256=' + base64.b64encode(sha256\_hash_digest) -  } - -  # returns properly formatted json response -  return json.dumps(response) -``` - -#### Example JSON response: - -With the route defined as above your webapp should return a response similar to below when navigating to https://your-app-domain/webhooks/twitter?crc_token=foo in your web browser. -``` -{ - "response_token": "sha256=x0mYd8hz2goCTfcNAaMqENy2BFgJJfJOb4PdvTffpwg=" -} -``` -#### Other examples: - -* [HERE](https://github.com/xdevplatform/account-activity-dashboard/blob/master/helpers/security.js) is an example CRC response method written in Node/JS. -* [HERE](https://github.com/xdevplatform/SnowBotDev/blob/master/app/controllers/snow_bot_dev_app.rb) is an example CRC response method written in Ruby (see the _generate\_crc\_response_ and the /GET route that receives CRC events). - - - -### Optional signature header validation - -When receiving a POST request from X, sending a GET request to create a webhook, or sending a GET request to perform a manual CRC, a hash signature will be passed in the headers as x-twitter-webhooks-signature. This signature can be used to validate the source of the data is X. The POST hash signature starts with sha256= indicating the use of HMAC SHA-256 to encrypt your X App Consumer Secret and payload. The GET hash is calculated from the query parameter string crc_token=$token&nonce=$nonce.  - -**Steps to validate a request** - -1. Create a hash using your consumer secret and incoming payload body. -2. Compare created hash with the base64 encoded x-twitter-webhooks-signature value. Use a method like [compare_digest](https://docs.python.org/2/library/hmac.html) to reduce the vulnerability to timing attacks. - - - -### Additional security guidelines - -The following are additional security guidelines to consider for your web application. Not having these guidelines implemented will not prevent your webhook from functioning, but are highly reccomended by the X Information Security team. If you are unfamilair with the below recommendations consult with your server administrator. - -#### X aggregate network blocks - -For added security you may wish to add the following aggregate network blocks to an allowlist: - -* 199.59.148.0/22 -* 199.16.156.0/22 -* 192.133.77.0/26 -* 64.63.15.0/24 - -* 64.63.31.0/24 -* 64.63.47.0/24 -* 202.160.128.0/24 -* 202.160.129.0/24 -* 202.160.130.0/24 - -#### Recommended server configurations - -* "A" rating on [ssllabs.com](http://ssllabs.com/) test -* **Enable TLS 1.2** -* Enable Forward Secrecy -* Turn off SSLv2 -* Turn off SSLv3 (because of POODLE) -* Turn off TLS 1.0 -* Turn off TLS 1.1 -* Turn off TLS Compression -* Turn off Session Tickets unless you rotate session ticket keys. -* Set the “ssl\_prefer\_server_ciphers” or “SSLHonorCipherOrder” option in the SSL Configuration “on”. -* Ensure the list of ciphers is a modern list such as: - `ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:DES-CBC3-SHA` - - -## Managing webhooks and subscriptions - -### Creating & changing webhooks - -In order to change webhook URLs, you must delete your existing webhook and then create a new one. Note that when you do this, you will be required to re-add user subscriptions to the new webhook. - -#### Webhook configuration management endpoints: - - -| | | -| :--- | :--- | -| **Method** | Enterprise | -| Registers a webhook URL / Generates a webhook_id | [POST webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) | -| Returns all webhook URLs and their statuses | [GET webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) | -| Delete app’s current webhook configuration | [DELETE webhooks/:webhook_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id) | -| Manually trigger a CRC request | [PUT webhooks/:webhook_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id) | - -#### Why can’t I just update the webhook URL? - -Why are webhook configurations immutable? X takes security very seriously. If your webhook URL is changed, there is a possibility that your application consumer key and consumer secret have been compromised. By requiring you to create a new webhook configuration, you are also required to re-subscribe to your user’s events. This requires the use of access tokens that a malicious party is less likely to possess. As a result, the likelihood that another party will receive your user’s private information is reduced. -  - -### Adding & removing User subscriptions - -Support for thousands of subscriptions is available with the enterprise tier. If you already have an account manager, please reach out to them with questions.  To apply for access to the enterprise APIs, [click here](https://developer.x.com/en/products/x-api/enterprise).  - -#### Subscription management endpoints -  - -| | | -| :--- | :--- | -| Method | Enterprise | -| Add new user subscription | [POST webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all) | -| Retrieve a user subscription | [GET webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all) | -| Returns a list of all active subscriptions | [GET webhooks/:webhook_id/subscriptions/all/list](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | -| Deactivates a user subscription using application only OAuth | [DELETE webhooks/:webhook\_id/subscriptions/:user\_id/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json) | - - - -Account Activity API: Enterprise - -**Please note**:  - -X needs to enable access to the Account Activity API for your developer App before you can start using the API. To this end, make sure to share the App ID that you intend to use for authentication purposes with your account manager or technical support team. - - -The [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) consists of a set of endpoints that allow you to create and manage user subscriptions to receive real-time account activities for all of your subscribed accounts through a single connection.  - -There are two authentication methods available with the Account Activity API ([OAuth 1.0a](/resources/fundamentals/authentication#oauth-1-0a-2) and [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). The authentication method that you should use will depend on which endpoint you are using. - -| | | | | -| :--- | :--- | :--- | :--- | -| **Description** | **Endpoint ** | OAuth 1.0a
(user context) | OAuth 2.0 Bearer Token (application-only) | -| Register a new webhook URL for the given application context | [POST account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks) | ✓ | | -| Return all URLs and their statuses for the given application | [GET account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) | | ✓ | -| Trigger a challenge response check (CRC) for a given webhook's URL | [PUT account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id) | ✓ | | -| Subscribe the application to a user’s account events | [POST account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all) | ✓ * | | -| Return a count of currently active subscriptions | [GET account_activity/subscriptions/count](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | | ✓ | -| Check if a webhook configuration is subscribed to a user’s events | [GET account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all) | ✓ * | | -| Return a list of currently active subscriptions | [GET account\_activity/webhooks/:webhook\_id/subscriptions/all/list](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all-list) | | ✓ | -| Delete a webhook | [DELETE account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id) | ✓ | | -| \[DEPRECATED\] Deactivate a subscription for the provided user context and application | [DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) | ✓ * | | -| Deactivate a subscription using application-only OAuth | [DELETE /account\_activity/webhooks/:webhook\_id/subscriptions/:user_id/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json) | | ✓ | -| Redelivers activities to a webhook | [POST /1.1/account\_activity/replay/webhooks/:webhook\_id/subscriptions/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#replay-api) | | ✓ | - -*_ Authentication requires the access tokens of the subscribing user. _ - -For those endpoints that require OAuth 1.0a user context authentication, you will need to provide the following credentials to authenticate the request:  - -* Consumer Keys (API Key and Secret) -* Access Tokens (Access Token and Secret) - -In the case of the following three endpoints, you perform write actions within the context of your application (no X users are involved). Therefore, the Access Tokens you need to provide are the ones belonging to your developer App. These can be generated directly from within the [Developer Console](https://developer.x.com/en/portal/projects-and-apps), under the “Keys and tokens” tab for your App.   - -* [POST account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks): Register a new webhook URL for the given application context -* [PUT account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id): Trigger a challenge response check (CRC) for a given webhook's URL -* [DELETE account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id): Delete a webhook - -On the other hand, in the case of the following three endpoints, you are making a request that allows your application to access protected data on behalf of a X user (for example, Direct Messages). You must therefore provide the Access Tokens that belong to the subscribing user in question. The required Access tokens can be obtained using the 3-legged OAuth flow (see [OAuth 1.0a: how to obtain a user’s Access Tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow)). These endpoints have been marked with an asterisk in the above table (*). - -* [POST account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all): Subscribe the application to a user’s account events -* [GET account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all): Check if a webhook configuration is subscribed to a user’s events -* [DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated): Deactivate a subscription for the provided user context and application \[DEPRECATED\] - - -**Please note**:  - -Make sure that your developer App is enabled for "Read, Write, and Direct Messages." You can change this setting in the [Projects & Apps section](https://developer.x.com/en/portal/projects-and-apps) of your developer account, under “App permissions” for the selected developer App. You will need to regenerate your App credentials after changing the permissions settings. - -A list of all endpoints available with the Account Activity API, including associated description and example cURL requests with authentication implementation examples, can be found in[the API reference documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-api-reference-index). - -For additional information, check out XDev’s [sample web app and helper scripts](https://github.com/xdevplatform/account-activity-dashboard-enterprise) to get started with the Enterprise Account Activity API. - - -**Please note**:  - -X needs to enable access to the Account Activity API for your developer App before you can start using the API. To this end, make sure to share the App ID that you intend to use for authentication purposes with your account manager or technical support team. - -The [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) consists of a set of endpoints that allow you to create and manage user subscriptions to receive real-time account activities for all of your subscribed accounts through a single connection.  - -There are two authentication methods available with the Account Activity API ([OAuth 1.0a](/resources/fundamentals/authentication#oauth-1-0a-2) and [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#oauth-2-0)). The authentication method that you should use will depend on which endpoint you are using. - -| | | | | -| :--- | :--- | :--- | :--- | -| **Description** | **Endpoint ** | OAuth 1.0a
(user context) | OAuth 2.0 Bearer Token (application-only) | -| Register a new webhook URL for the given application context | [POST account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks) | ✓ | | -| Return all URLs and their statuses for the given application | [GET account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) | | ✓ | -| Trigger a challenge response check (CRC) for a given webhook's URL | [PUT account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id) | ✓ | | -| Subscribe the application to a user’s account events | [POST account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all) | ✓ * | | -| Return a count of currently active subscriptions | [GET account_activity/subscriptions/count](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | | ✓ | -| Check if a webhook configuration is subscribed to a user’s events | [GET account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all) | ✓ * | | -| Return a list of currently active subscriptions | [GET account\_activity/webhooks/:webhook\_id/subscriptions/all/list](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all-list) | | ✓ | -| Delete a webhook | [DELETE account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id) | ✓ | | -| \[DEPRECATED\] Deactivate a subscription for the provided user context and application | [DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) | ✓ * | | -| Deactivate a subscription using application-only OAuth | [DELETE /account\_activity/webhooks/:webhook\_id/subscriptions/:user_id/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json) | | ✓ | -| Redelivers activities to a webhook | [POST /1.1/account\_activity/replay/webhooks/:webhook\_id/subscriptions/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#replay-api) | | ✓ | - -*_ Authentication requires the access tokens of the subscribing user. _ - -For those endpoints that require OAuth 1.0a user context authentication, you will need to provide the following credentials to authenticate the request:  - -* Consumer Keys (API Key and Secret) -* Access Tokens (Access Token and Secret) - -In the case of the following three endpoints, you perform write actions within the context of your application (no X users are involved). Therefore, the Access Tokens you need to provide are the ones belonging to your developer App. These can be generated directly from within the [Developer Console](https://developer.x.com/en/portal/projects-and-apps), under the “Keys and tokens” tab for your App.   - -* [POST account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks): Register a new webhook URL for the given application context -* [PUT account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id): Trigger a challenge response check (CRC) for a given webhook's URL -* [DELETE account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id): Delete a webhook - -On the other hand, in the case of the following three endpoints, you are making a request that allows your application to access protected data on behalf of a X user (for example, Direct Messages). You must therefore provide the Access Tokens that belong to the subscribing user in question. The required Access tokens can be obtained using the 3-legged OAuth flow (see [OAuth 1.0a: how to obtain a user’s Access Tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow)). These endpoints have been marked with an asterisk in the above table (*). - -* [POST account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all): Subscribe the application to a user’s account events -* [GET account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all): Check if a webhook configuration is subscribed to a user’s events -* [DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated): Deactivate a subscription for the provided user context and application \[DEPRECATED\] - - -**Please note**:  - -Make sure that your developer App is enabled for "Read, Write, and Direct Messages." You can change this setting in the [Projects & Apps section](https://developer.x.com/en/portal/projects-and-apps) of your developer account, under “App permissions” for the selected developer App. You will need to regenerate your App credentials after changing the permissions settings. - -A list of all endpoints available with the Account Activity API, including associated description and example cURL requests with authentication implementation examples, can be found in[the API reference documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-api-reference-index). - -For additional information, check out XDev’s [sample web app and helper scripts](https://github.com/xdevplatform/account-activity-dashboard-enterprise) to get started with the Enterprise Account Activity API. - - -## Retries - -`Enterprise` - -One of the benefits of the enterprise tier of the Account Activity API is a retry mechanism for webhook events. If a 'success' 200 HTTP response code is not received, the X server will initiate a retry mechanism, resending the webhook event up to three times over a five-minute period. This webhook event retry service helps provide reliability and event recovery when network problems occur and during client-side service interruptions and deploys. -  - -### What are retries? - -The Account Activity API provides a retry feature when the client's web app does not return a 'success' 200 response for an account activity webhook event. When the client-side does not confirm the successful receipt of an event, X assumes the event was not received. If a non-200 response is received, a response isn't received within three seconds, or we don't receive a response at all, we retry the request and leave that open for three seconds. This means that you have roughly five seconds over two attempts to respond to receive the activity that we are trying to send to your webhook URL. In the event that your server doesn't response or returns a transient error, we will retry for five minutes. There will be a total of three retry attempts to confirm validation. This allows redundancy and insurance that you receive all webhook events. Note that subscriptions with retries will get retried events for any/all activities for all subscribed users on their webhook. - -If you do not confirm validation within these eight attempts, the activity will no longer be available via the Account Activity API.  - - -### Retry timeline - -The Account Activity API will retry up to three times over a five-minute period until a 200 response is received.  Refer to the table below for more details. After around five minutes, the activity cannot be resent through the Account Activity API. You will need to use other X endpoints to collect missed data. For example, the [search APIs](/x-api/enterprise-gnip-2.0/fundamentals/search-api) can be used to retrieve relevant Posts, Retweets, Quote Tweets, Mentions, and Replies. Missed Direct Messages can be retrieved with [this endpoint](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events). - -#### Retries timeline - -| | -| :--- | -| Activity created, POST to the webhook URL from Account Activity API and times out in three seconds. | -| Wait three seconds after previous timeout finishes, then POST to the webhook URL from Account Activity API and times out in three seconds. | -| Wait 27 seconds after previous timeout finishes, then POST to the webhook URL from Account Activity API and times out in three seconds. | -| Wait 242 seconds after previous timeout finishes, then POST to the webhook URL from Account Activity API and times out in three seconds | -| The Account Activity API will stop attempting to POST after this. Client must use other X endpoints to recover data. | - - -## Account Activity data object structure - -| Object | Details | -| :--- | :--- | -| for\_user\_id | Identifies the user subscription subscribed that the event is related to. | -| is\_blocked\_by | (conditional) Shown only when another user mentions your subscribed user. Included if true for Post mention events only. | -| source | The user that is performing the activity. For example, the user that is following, blocking, or muting is the source user. | -| target | The user that the activity applies to. For example, the user that is being followed, blocked, or muted is the target user. | - - -**Available Activities** - -| Message Type | Details | -| :--- | :--- | -| [tweet\_create\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#tweet-create-events-posts-retweets-replies-quotetweets) | Post status payload when any of the following actions are taken by or to the subscription user: Posts, Retweets, Replies, @mentions, QuoteTweets, Retweet of Quote Tweets. | -| [favorite_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#favorite-events) | Favorite (like) event status with the user and target. | -| [follow_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#follow-events) | Follow event with the user and target. | -| [unfollow_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#unfollow-events) | Unfollow event with the user and target. | -| [block_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#block-events) | Block event with the user and target. | -| [unblock_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#unblock-events) | Unblock event with the user and target. | -| [mute_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#mute-events) | Mute event with the user and target. | -| [unmute_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#unmute-events) | Unmute event with the user and target. | -| [user_event](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#user-event) | Revoke events sent when a user removes application authorization and subscription is automatically deleted. | -| [direct\_message\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-events) | Direct message status with the user and target when a direct message is sent or received. | -| [direct\_message\_indicate\_typing\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-indicate-typing-events) | Direct message typing event with the user and target. | -| [direct\_message\_mark\_read\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-mark-read-events) | Direct message read event with the user and target. | -| [tweet\_delete\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#tweet-delete-events) | Notice of deleted Posts to make it easier to maintain compliance. | - -**Payload examples** - -See the payload examples below for each Account Activity event described in the table above. - -#### tweet\_create\_events (Posts, Retweets, Replies, QuoteTweets)  - -``` -{ - "for_user_id": "2244994945", - "tweet_create_events": [ - { - - } - ] -} -``` - - -#### tweet\_create\_events (@mentions)  - -``` -{ - "for_user_id": "2244994945", - "user_has_blocked": "false", - "tweet_create_events": [ - { - - } - ] -} -``` - -#### favorite_events - -``` -{ - "for_user_id": "2244994945", - "favorite_events": [{ - "id": "a7ba59eab0bfcba386f7acedac279542", - "created_at": "Mon Mar 26 16:33:26 +0000 2018", - "timestamp_ms": 1522082006140, - "favorited_status": { - - }, - "user": { - - } - }] -} -``` - -#### follow_events - -``` -{ - "for_user_id": "2244994945", - "follow_events": [{ - "type": "follow", - "created_timestamp": "1517588749178", - "target": { - - }, - "source": { - < User Object > - } - ] - } -} -``` - -#### unfollow_events - -``` -{ - "for_user_id": "2244994945", - "follow_events": [{ - "type": "unfollow", - "created_timestamp": "1517588749178", - "target": { - - }, - "source": { - < User Object > - } - ] - } -} -``` - -#### block_events - -``` -{ - "for_user_id": "2244994945", - "block_events": [{ - "type": "block", - "created_timestamp": "1518127020304", - "source": { - - }, - "target": { - - } - }] -} -``` - -#### unblock_events -``` -{ - "for_user_id": "2244994945", - "block_events": [{ - "type": "unblock", - "created_timestamp": "1518127020304", - "source": { - - }, - "target": { - - } - }] -} -``` - -#### mute_events - -``` -{ - "for_user_id": "2244994945", - "mute_events": [ - { - "type": "mute", - "created_timestamp": "1518127020304", - "source": { - - }, - "target": { - - } - } - ] -} -``` - -#### unmute_events - -``` -{ - "for_user_id": "2244994945", - "mute_events": [ - { - "type": "unmute", - "created_timestamp": "1518127020304", - "source": { - - }, - "target": { - - } - } - ] -} -``` - -#### user_event - -``` -{ - "user_event": { - "revoke": { - "date_time": "2018-05-24T09:48:12+00:00", - "target": { - "app_id": "13090192" - }, - "source": { - "user_id": "63046977" - } - } - } -} -``` - -#### direct_message_events - -``` -{ - "for_user_id": "4337869213", - "direct_message_events": [{ - "type": "message_create", - "id": "954491830116155396", - "created_timestamp": "1516403560557", - "message_create": { - "target": { - "recipient_id": "4337869213" - }, - "sender_id": "3001969357", - "source_app_id": "13090192", - "message_data": { - "text": "Hello World!", - "entities": { - "hashtags": [], - "symbols": [], - "user_mentions": [], - "urls": [] - } - } - } - }], - "apps": { - "13090192": { - "id": "13090192", - "name": "FuriousCamperTestApp1", - "url": "https://x.com/furiouscamper" - }, - "users": {}, - "3001969357": { - "id": "3001969357", - "created_timestamp": "1422556069340", - "name": "Jordan Brinks", - "screen_name": "furiouscamper", - "location": "Boulder, CO", - "description": "Alter Ego - X PE opinions-are-my-own", - "url": "https://t.co/SnxaA15ZuY", - "protected": false, - "verified": false, - "followers_count": 22, - "friends_count": 45, - "statuses_count": 494, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg" - }, - "4337869213": { - "id": "4337869213", - "created_timestamp": "1448312972328", - "name": "Harrison Test", - "screen_name": "Harris_0ff", - "location": "Burlington, MA", - "protected": false, - "verified": false, - "followers_count": 8, - "friends_count": 8, - "profile_image_url": "null", - "statuses_count": 240, - "profile_image_url_https": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png" - } - } -} -``` - -#### direct_message_indicate_typing_events - -``` -{ - "for_user_id": "4337869213", - "direct_message_indicate_typing_events": [{ - "created_timestamp": "1518127183443", - "sender_id": "3284025577", - "target": { - "recipient_id": "3001969357" - } - }], - "users": { - "3001969357": { - "id": "3001969357", - "created_timestamp": "1422556069340", - "name": "Jordan Brinks", - "screen_name": "furiouscamper", - "location": "Boulder, CO", - "description": "Alter Ego - X PE opinions-are-my-own", - "url": "https://t.co/SnxaA15ZuY", - "protected": false, - "verified": false, - "followers_count": 23, - "friends_count": 47, - "statuses_count": 509, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg" - }, - "3284025577": { - "id": "3284025577", - "created_timestamp": "1437281176085", - "name": "Bogus Bogart", - "screen_name": "bogusbogart", - "protected": true, - "verified": false, - "followers_count": 1, - "friends_count": 4, - "statuses_count": 35, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/763383202857779200/ndvZ96mE_normal.jpg" - } - } -} -``` - - -#### direct_message_mark_read_events - -``` -{ - "for_user_id": "4337869213", - "direct_message_mark_read_events": [{ - "created_timestamp": "1518452444662", - "sender_id": "199566737", - "target": { - "recipient_id": "3001969357" - }, - "last_read_event_id": "963085315333238788" - }], - "users": { - "199566737": { - "id": "199566737", - "created_timestamp": "1286429788000", - "name": "Le Braat", - "screen_name": "LeBraat", - "location": "Denver, CO", - "description": "data by day @X, design by dusk", - "protected": false, - "verified": false, - "followers_count": 299, - "friends_count": 336, - "statuses_count": 752, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/936652894371119105/YHEozVAg_normal.jpg" - }, - "3001969357": { - "id": "3001969357", - "created_timestamp": "1422556069340", - "name": "Jordan Brinks", - "screen_name": "furiouscamper", - "location": "Boulder, CO", - "description": "Alter Ego - X PE opinions-are-my-own", - "url": "https://t.co/SnxaA15ZuY", - "protected": false, - "verified": false, - "followers_count": 23, - "friends_count": 48, - "statuses_count": 510, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg" - } - } -} -``` - -#### tweet_delete_events - -``` -{ - "for_user_id": "930524282358325248", - "tweet_delete_events": [ -{ - "status": { - "id": "1045405559317569537", - "user_id": "930524282358325248" - }, - "timestamp_ms": "1432228155593" - } - ] -} -``` - -## Account Activity Replay API - -`Enterprise` - -The Account Activity Replay API is a data recovery tool that allows you to retrieve events from as far back as five days. It should be utilized to recover data in scenarios where your [webhook](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) server misses events, -- whether due to disconnections lasting longer than the [retry window](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#retries), or for those disaster recovery scenarios where you need a few days to restore your system back to normal. - -The Account Activity Replay API was developed for any scenario where you fail to ingest [activities](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) for a period of time. It delivers activities to the same webhook used for the original real-time delivery of activities. This product is a recovery tool and not a backfill tool, which means events will only be replayed if a previous delivery of them was attempted. The Account Activity Replay API cannot deliver events for a time period prior to a subscription’s creation time. - -### Using Account Activity Replay API - -If your account is configured with Replay functionality, you can make requests in a similar manner as requests to the Account Activity API. It is important to note that your request must specify a webhook id parameter to indicate which webhook’s activities you would like to replay. In other words, a Replay request asks Account Activity Replay API to retrieve events from a start date and time to an end date and time based on the webhook id and application id. - -Please note that UTC time is expected. These activities are delivered through the registered webhook associated with the id at a rate of up to 2,500 events per second. Also keep in mind that only one Replay job per webhook may be running at a time, although all subscriptions that were active during the date/time specified on that webhook will be replayed. - -Events are delivered beginning with the first (oldest) minute of the specified time period, continuing chronologically (as best as possible) until the final minute is delivered. At that point, Replay will deliver a [job completion event](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#job-completed-successfully-message) to the webhook. Because we work chronologically in delivering activities, if there are little or no matching results near the start time, there will likely be a period of time before the first results are delivered. - -### Limitations - -Replay is intended as a tool for easily recovering activities as far back as five days ago, but it will not deliver events prior to a subscription’s creation time. For example, if three days ago, you added a new subscription and ran a Replay job with a window for five days prior to today, you would only receive data for the three days that this new subscription was active. - -### Data availability and types - -Activities from the Account Activity Replay API are available five days from the initiation of the request, with new data becoming available roughly 10 minutes after a given activity is created. You will be able to make requests specifying a timeframe within this five day window using the from\_date and to\_date parameters within the request. Events that were originally delivered prior to having access to Replay cannot be replayed. For example, if your account was enabled for access to the Account Activity Replay API on June 1, 2019 at 3:30PM UTC, you would not be able to use Replay to retrieve any events prior to that date and time. - -Continue to the [Account Activity Replay API reference](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) - -## Migration introduction - -**We retired the Site Streams, User Streams, and standard beta version of the Account Activity API - DM Only products in 2018. If you had been using those products, please make sure to migrate over to the premium or enterprise version of the Account Activity API.** - -**We have also retired the legacy Direct Message endpoints. If you had been using those endpoints, please make sure to migrate over to either the new DM endpoints, or to the premium or enterprise version of the Account Activity API. ** - -**Please review [this announcment](https://devcommunity.x.com/t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746) to learn more.** - -Here are the endpoints that will be affected by these changes: - -* User Streams -* Site Streams -* GET direct_messages -* GET direct_messages/sent -* GET direct_messages/show -* POST direct_messages/new -* POST direct_messages/destroy -   - -We have new endpoints and services available that provide similar access and, for Direct Messages, some additional functionality: - -* Account Activity API [enterprise](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) and [premium](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-api-reference-index) -* [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) -* [GET direct_messages/events/show](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) -* [POST direct_messages/events/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) -* [POST direct_messages/events/destroy](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/delete-message-event) - -To help you make a smooth migration to these new endpoints and services we have two migration guides: - -* [Account Activity API migration guide](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-guide-moving-from-user-streams-site-streams-to-account-activity-api) for those going from User Streams and Site Streams to our new webhooks based service -* [Direct Message migration guide](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/guides/direct-message-migration) for those migrating between Direct Message REST endpoints -   - -Additionally, we have a [series of videos](https://www.youtube.com/playlist?list=PLFKjcMIU2WshGG6Yj940XM7Z6BFs1zfBg) about the Account Activity API and how to get started. - -And, finally, we have code samples to further your understanding and help you get started quickly: - -* The [Account Activity Dashboard](https://github.com/xdevplatform/Account-Activity-dashboard) is a sample Node.js web app with helper scripts to get started with the Account Activity API. -* [SnowBot](https://github.com/xdevplatform/SnowBotDev) is a sample chatbot using the Account Activity API and REST Direct Message endpoints. It’s written in Ruby, uses the Sinatra web app framework, and is deployed on Heroku. - - -## Migration Guide: Moving from User Streams/Site Streams to Account Activity API - -**As of August 23rd, 2018, we retired both Site Streams and User Streams. Please make sure to migrate over to the Account Activity API.** - -**Please review [this announcement](https://devcommunity.x.com/t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746) to learn more.** - -This guide is designed to help you migrate from legacy User Streams and Site Streams APIs to their replacement, the Account Activity API. Below you will find a summary of the changes, new features list, as well as key differences and considerations to help with the transition. For guidance in migrating from basic DM endpoints, please refer to the [Direct Message migration guide](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/guides/direct-message-migration). - -### Summary of changes - -The Account Activity API will deliver you events for authenticated and subscribed accounts via webhooks as opposed to a streaming connection like with User Streams and Site Streams. - -#### Deprecated APIs - -GET user - -GET site  (including control streams: GET site/c/:stream\_id,  GET site/c/:stream\_id/info.json,  GET site/c/:stream\_id/friends/ids.json,  POST site/c/:stream\_id/add\_user.json,  POST /site/c/:stream\_id/remove_user.json) - -#### Replacement APIs - -[Enterprise Account Activity API - All Activities](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) - -### Differences & migration considerations - -**API format:** The new Account Activity API operates differently than User Streams and Site Streams. You will need to alter your web app to receive data with webhooks. You can find more information on webhooks [here](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks). - -**Data Available:** Another key difference you will notice is in regards to the data being delivered. X will no longer send events from people that you follow on X (aka your home timeline). This was an intentional change and is not something we plan to alter going forward. - -**Reliability:** Unlike streaming, webhooks enable confirmation of delivery and options to retry POSTed activities that do not make it to the webhook URL.  This gives more assurance that the app is receiving all applicable activities, even if there are brief disconnections or periods of downtime. - - -### New features - -The Account Activity API offers many new features, most notably that data is now delivered via webhooks as opposed to streaming. Webhooks offer many benefits compared to streaming, but the most prominent are speed and reliability. The API will send you data in the form of JSON events as they become available and you will no longer need to maintain an active connection or poll the endpoint. This limits the need for redundancy features and increases efficiency overall. More information on webhooks can be found in the [technical documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks). - - -### Managing user subscriptions - -The Account Activity API allows multiple subscriptions for a single registered webhook.  This allows multiple user subscriptions activities to be delivered to the same location, similar to the Site Streams architecture, with webhooks.  This means you can track subscriptions, as they pertain to your subscription limits, independently from the webhook connection.  This also allows scalability from only one or a few subscriptions to thousands of subscriptions for a single webhook. - -### **How to Migrate** - -### **Follow the steps below to easily migrate from the Site Streams API to the Account Activity API** - -**Step 1: Decide on a Package** - -Depending on how you are currently operating with User Streams or Site Streams, you should consider moving to either the enterprise or premium version of the Account Activity API.  Consider the number of applications or authorized users you are currently supporting and scale appropriately to the volume and reliability needed.  When deciding on the package that best suits your needs, some things worth considering are: - -* Number of webhooks needed -* Current/projected subscriptions/authorized users managed on your application -* Current number of X client applications -* The level of support you'd prefer from X (forum support or managed enterprise level 1:1 support) -* Price of each package - -**Step 2:** **Check the Setup of your X app in the Developer Console** - -The [X app](/resources/fundamentals/developer-apps) currently used for User Streams or Site Streams will be listed for the owning user within the [Developer Console](/resources/fundamentals/developer-portal). This X app can also be used for Account Activity API to retain authorized users for that application.  A new app can also be created, and users can be re-authorized for this new app if desired.  If you are creating a new app on behalf of a business, it is recommended that you create the app with a corporate X @handle account. - -* Enable “Read, Write and Access direct messages” on the [permissions](/resources/fundamentals/developer-apps#app-permissions) tab of your X app page.  - *Note that changing these settings is not retroactive, any authorized users will keep the authorization settings from the time at which they were authorized. If a user has not already given you read, write and direct message access, you will need to have that user re-authorize your application. -* If you are unfamiliar with [X Sign-in](/resources/fundamentals/authentication#log-in-with-x) and how user contexts work with the X API review [Obtaining Access Tokens](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks). -* Generate access tokens for the X app owner at the bottom of the “Keys and Tokens” tab. On this same tab take note of your Consumer Key, Consumer Secret, Access Token and Access Token Secret. You will need these to use the API. -* Generate a bearer token using your Consumer Key and Consumer Secret for [application-only](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only) API methods. - -**Step 3: Setup & Configure Your Webhooks** - -* Create a web app with an endpoint to use as your webhook to receive events (e.g. https://your\_domain.com/webhook/twitter or https://webhooks.your\_domain.com). -* Use your Consumer Key, Consumer Secret, Access Token and Access Token Secret when creating your webhook, Note that your endpoint must return a JSON response with a response\_token that is a base64 encoded HMAC SHA-256 hash created from the crc\_token and your app Consumer Secret. - -* Review [Securing Webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#securing-webhooks) documentation taking special note of the Challenge Response Check (CRC) requirements. -* Make sure your webhook supports POST requests for incoming events and GET requests for the CRC. -* Make sure your webhook has low latency (\<3 seconds to respond to POST requests) - -**Step 4: Validate Your Webhook Setup** - -* Webhook APIs will secure your webhooks in two ways: - -               \- Require challenge response checks to validate that the webhook owner is the web app owner. - -               \- A signature header in each POST request for your web app to validate the source. - -* In order to verify that you are both the owner of the web app and the webhook URL, X will perform a Challenge Response Check (CRC), which is not to be confused with a cyclic redundancy check. -* A GET request with a parameter named crc\_token will be sent to your webhook URL. Your endpoint must return a JSON response with a response\_token that is a base64 encoded HMAC SHA-256 hash created from the crc_token and your app Consumer Secret. -* The crc\_token should be expected to change for each incoming CRC request. The crc\_token should be used as the message in the calculation, where your Consumer Secret is the key. -* In the event that the response is invalid, events will cease to be sent to the registered webhook. - -**Step 5: Create Subscriptions for Each User Stream or Site Streams Authorized User** - -Converting to the Account Activity API from User Streams: - -* Generate a list of your current user subscriptions on User Streams -* Set up your new Account Activity API subscriptions using the request:  _POST account\_activity/all/:env\_name/subscriptions_ -* Confirm your Account Activity API subscriptions using the request:  _GET account\_activity/all/:env\_name/subscriptions/list -  _ - -Converting to the Account Activity API from Site Streams: (using control streams): - -* Generate a list of your current subscriptions on Site Streams using the request:  _GET /1.1/site/c/:stream_id/info.json_ -* Set up your new Account Activity API subscriptions using the request:  _POST account\_activity/all/:env\_name/subscriptions_ -* Confirm your Account Activity API subscriptions using the request:  _GET account\_activity/all/:env\_name/subscriptions/list -  _ - -Registering a Webhook and Creating Subscriptions (not migrating from Site Streams or User Streams) - -* Register your webhook URL with your app using [POST webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) and receive a webhook_id. -* Use the returned webhook_id to add user subscriptions with [POST webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all). - -### The Account Activity dashboard (sample Account Activity API application) - -We've created a sample app to make testing the Account Activity API a little quicker:    - -* Download the Account Activity Dashboard sample application [here](https://github.com/xdevplatform/Account-Activity-dashboard) (it uses Node.js) -* Follow the instructions on the README to install and launch the app -* Once the application has been launched, you can use the UI to easily set up your webhook and create a new subscription - -### Available Activities - -| Message Type | Details | -| :--- | :--- | -| [tweet\_create\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#tweet-create-events-posts-retweets-replies-quotetweets) | Post status payload when any of the following actions are taken by or to the subscription user: Posts, Retweets, Replies, @mentions, QuoteTweets | -| [favorite_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#favorite-events) | Favorite (like) event status with the user and target. | -| [follow_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#follow-events) | Follow event with the user and target. | -| [block_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#block-events) | Block event with the user and target. | -| [mute_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#mute-events) | Mute event with the user and target. | -| [direct\_message\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-events) | Direct message status with the user and target. | -| [direct\_message\_indicate\_typing\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-indicate-typing-events) | Direct message typing event with the user and target. | -| [direct\_message\_mark\_read\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-mark-read-events) | Direct message read event with the user and target. | - -### Deprecated streaming message types  - -| | | -| :--- | :--- | -| Blank lines | Blank lines will no longer be delivered in the Account Activity API as they were used as keep-alive messages in User Streams and Site Streams. | -| Limit notices | Limit notices will no longer be sent to a given webhook.  Instead, users can call the API to get current usage of available handles. This will be included in the Developer Console at some time in the future. | -| Disconnect messages | Disconnect notices will no longer be necessary as webhooks do not rely on an active connection. | -| Stall warnings | Stall warnings will no longer be necessary as webhooks do not rely on an active connection being able to handle large numbers of incoming messages. | -| Friends list | Friends lists will no longer be sent proactively. There will now be a REST endpoint to get this information. | - -### Deprecated event types - -| | | | | | -| :--- | :--- | :--- | :--- | :--- | -| **Description** | **Event Name** | **Source** | **Target** | **Target Object** | -| User deletes a Post | delete | Current user | Current User | Post | -| Followed user deletes a Post | delete | Followed user | Followed user | Post | -| User unfavorites a Post | unfavorite | Current user | Post author | Post | -| User’s Post is unfavorited | unfavorite | Unfavoriting user | Current user | Post | -| User unfollows someone | unfollow | Current user | Followed user | Null | -| User creates a list | list_created | Current user | Current user | List | -| User deletes a list | list_destroyed | Current user | Current user | List | -| User edits a list | list_updated | Current user | Current user | List | -| User adds someone to a list | list\_member\_added | Current user | Added user | List | -| User is added to a list | list\_member\_added | Adding user | Current user | List | -| User removes someone from a list | list\_member\_removed | Current user | Removed user | List | -| User is removed from a list | list\_member\_removed | Removing user | Current user | List | -| User subscribes to a list | list\_user\_subscribed | Current user | List owner | List | -| User’s list is subscribed to | list\_user\_subscribed | Subscribing user | Current user | List | -| User unsubscribes from a list | list\_user\_unsubscribed | Current user | List owner | List | -| User’s list is unsubscribed from | list\_user\_unsubscribed | Unsubscribing user | Current user | List | -| User updates their profile | user_update | Current user | Current user | Null | -| User updates their protected status | user_update | Current user | Current user | Null | - - -## Direct Message migration guide - -**On September 17th, 2018 we retired the legacy Direct Message endpoints. -If you had been using those endpoints, please make sure to migrate over to the new Direct Message endpoints or the Account Activity API.** - -**Please review [this announcment](https://devcommunity.x.com//t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746) to learn more.** - -This guide is designed to help you migrate from legacy Direct Message REST APIs to their enhanced replacements which have graduated from beta. Below you will find a summary of the changes, a new features list, and key differences and considerations to help with the transition. The new Direct Message endpoints are available now to all developers. For guidance in migrating from User Streams or Site Streams, see the [migration guide to Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-guide-moving-from-user-streams-site-streams-to-account-activity-api). - -* [Summary of changes](#summary) -* [New features](#features) -* [Sending Direct Messages](#sending) -* [Receiving Direct Messages](#receiving) -* [Deleting Direct Messages](#deleting) - -### Summary of changes - -If you are still using the following DM endpoints, you will have to migrate to the newer endpoints.  - -| Deprecated endpoint | New migration alternative | -| :--- | :--- | -| [POST direct_messages/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) | [POST direct_messages/events/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) | -| [GET direct_messages/show](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) | [GET direct_messages/events/show](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) | -| [GET direct_messages](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) | [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) | -| [GET direct_messages/sent](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) | [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) | -| [POST direct_messages/destroy](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/delete-message-event) | [DELETE direct_messages/events/destroy](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/delete-message-event "GET direct_messages/events/list") | - -### New features - -The new Direct Message API endpoints support a number of new capabilities and provide improved access to previous Direct Messages. New features include: - -* Support for media attachments (image, GIF, and video). -* Ability to prompt users for structured replies with a predefined options list. -* Up to 30 days of access to past Direct Messages. - -For a full list of new Direct Message features and additional new API endpoints refer to the [technical documentation](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/overview). -  - -### Differences & migration considerations - -The new API endpoints behave very differently from their previous counterparts. Simply updating the endpoint URLs will result in errors in your application. Consider the following when updating your application for the migration. - -#### New Direct Message object - -The first thing you are likely to notice is the new object structure of Direct Messages. This new Message Create object structure has been introduced to support new capabilities like [Quick Replies](https://developer.x.com/en/docs/x-api/v1/direct-messages/quick-replies/overview) and [Attachments](https://developer.x.com/en/docs/x-api/v1/direct-messages/message-attachments/overview). The new object also contains a smaller condensed user object. Your application will need to be updated to account for this new object structure when parsing and potentially in data models or storage. For descriptions of each property see the [full documentation on the Message Create Object](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/guides/message-create-object). - -**Example message create object** - -```json -{ - "type": "message_create", - "id": "1234858592", - "created_timestamp": "1392078023603", - "initiated_via": { - "tweet_id": "123456", - "welcome_message_id": "456789" - }, - "message_create": { - "target": { - "recipient_id": "1234858592" - }, - "sender_id": "3805104374", - "source_app_id": "268278", - "message_data": { - "text": "Blue Bird", - "entities": { - "hashtags": [], - "symbols": [], - "urls": [], - "user_mentions": [], - }, - "quick_reply_response": { - "type": "options", - "metadata": "external_id_2" - }, - "attachment": { - "type": "media", - "media": { - ... - } - } - } - } -``` -#### Summary - -* Entirely new Direct Message object structure. -* Condensed user object. -* New information provided (quick reply responses, attachments, etc). - - - -### Sending Direct Messages - -[POST direct_messages/events/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) is a direct replacement for sending Direct Messages. The most significant difference with this endpoint is that all information is now sent as JSON in the POST request body as opposed to individual POST params. - -**Example Twurl request** -```bash -twurl -A 'Content-type: application/json' -X POST /1.1/direct\_messages/events/new.json -d '{"event": {"type": "message\_create", "message\_create": {"target": {"recipient\_id": "4534871"}, "message_data": {"text": "Hello World!"}}}}' -``` -Note in the above request that the content-type is set to application/json as opposed to application/x-www-form-urlencoded. Additionally, if you are constructing the OAuth 1.0a signature, note that the JSON body is not included in the generation of the signature. Most OAuth libraries already account for this. If you are using [twurl](https://github.com/twitter/twurl), ensure you are using at least version 0.9.3. - -#### Summary - -* Message is defined in JSON POST body -* Content-type header must be set to application/json -* JSON body is not included in the generation of the OAuth signature. -   - -### Retrieving Direct Messages - -Retrieving past Direct Message is now accomplished with a single API endpoint: [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events). The significant difference with this new endpoint is that it now returns both sent and received messages in reverse chronological order. This may make it easier to rebuild a conversation. However, if you are only looking for sent or received messages you will need to post-process the response by referring to the sender_id property. - -Pagination is now based on a cursor value rather an ID of a Direct Message. A cursor property is returned with each response. [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) will return up to 30 days of past messages, regardless of how many messages exist within the past 30 days. When a cursor is not returned, there are no more messages to be returned. The method for accessing individual Direct Messages with [GET direct_messages/events/show](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) remains the same, although the Direct Message object returned has a different structure as described previously. - -Finally, real-time access to Direct Messages will now be accomplished via webhook with the [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity). For guidance in migrating from User Streams or Site Streams, see the migration guide to Account Activity API for more information. - -#### Summary - -* Sent and Received messages are now returned on the same endpoint. -* Up to 30 days of messages returned. -* Cursor based pagination. -* Real-time access to Direct Message via webhook. - -### Deleting Direct Messages - -Direct Messages can now be deleted with DELETE direct_messages/events/destroy. The interface is largely the same requiring the ID of the message to delete. The key differences is the endpoint now requires a DELETE request instead of a POST request. - -How deleted Direct Messages are reflected in official X clients remains the same. Direct Messages are only removed from the interface of the user context provided. Other members of the conversation can still access the Direct Message. - -#### Summary - -* Deleting a Direct Message requires the ID. -* New endpoint requires a DELETE request. -* How deleted Direct Messages are reflected in official X clients remains unchanged. - -**Questions about migrating to the new Direct Message endpoints? -**Post your question to the developer community forum on [devcommunity.com](https://devcommunity.x.com/). - - -## Frequently Asked Questions - -### General - -**What are the advantages of using the Account Activity API?** - -The Account Activity API uses webhooks, meaning that unlike for the streaming APIs we don't require you to have an open connection for us to send you information. Webhooks are also different from Rest APIs because you don't have to pull us hundreds of times every 15 minutes to get the data you care about. This increases the efficiency between a user and your app, as it delivers data when it happens. - -The Account Activity API has a number of benefits: - -1. **Speed**: we deliver data at the speed of X. -2. **Simplicity**: we deliver all of an account's events, through one single webhook connection. The activities delivered in the API include Posts, @mentions, replies, Retweets, Quote Tweets, Retweets of Quote Tweets, favorites, Direct Messages sent, Direct Messages received, follows, blocks, mutes.  -3. **Scale**: you receive all of the activities for an account that you manage without being restricted by any rate limits of event caps. - -The Account Activity API is available as a premium sandbox, premium paid, and enterprise offering, so you can scale as you require more accounts for liability features or additional functionality. - -To get started, download sample code snippets from [GitHub](https://github.com/xdevplatform/account-activity-dashboard). -  - -**How do I identify which product tier is best for me?** - -Please read through our [Account Activity API Overview](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) page to learn more about the differences between the Premium options and the Enterprise option.  -  - -**What is the difference between a Premium environment and an Enterprise webhook?** - -There is no difference. Each Premium environment will have its own webhook_id. -  - -**I need a development, staging and production environment for Account Activity API, is this possible?** - -Yes! With the paid tiers of Account Activity API (Paid Premium and Enterprise), it's possible to register multiple webhook URLs and manage subscriptions separately for each through the API methods. Additionally, multiple client apps may be added to an allowlist to maintain authorization for your current authorized users. -  - -**Do you have any step-by-step guides on how to get set up with the Account Activity API?** - -As a matter of fact, we do! - -* If you are just getting started, we recommend that you visit our [Getting started with webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks) guide - -* Follow along with our X Dev supported scripts:  - * [Account Activity API dashboard](https://github.com/xdevplatform/account-activity-dashboard), a node web app that displays webhook events. - * The [SnowBot chatbot](https://github.com/xdevplatform/SnowBotDev), a Ruby web app built on the Account Activity and Direct Message APIs. This code base includes a [script](https://github.com/xdevplatform/SnowBotDev/wiki/Account-Activity-API-setup-script) to help set up Account Activity API webhooks. -   - -**Is there a way to recover data if our system goes down for a period of time?** - -With the paid tiers of Account Activity API (Paid Premium and Enterprise), our system will [retry](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#retries) to send the activities to you several times over a four hour period. If your system does not respond within that four hour period, then the activity will be lost and you will have to use other REST endpoints to recover data within 7 days. - -We suggest that you use your different webhooks, or environments, as a redundancy tool like the [Account Activity Replay API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-replay-api) to ensure that you don't miss any activities if one of your systems goes down. -  - -**What authentication do I have to use with the Account Activity API?** - -The authorization methods required for Account Activity API is described per method in the [API reference pages](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-api-reference-index). If you are just starting out with X authentication, we recommend that you read through [this section](/resources/fundamentals/authentication). - - -**What is a challenge-response check (CRC)?** - -The Account Activity API challenge response check is a security feature put in place to ensure that the Account Activity API’s activities are being sent to the proper developer. It also can be used by developers to ensure that the data that they are receiving is coming from X. X will automatically send a CRC to your webhook URL once every 24 hours, starting the last time the webhook URL was validated. Your system must respond with a valid response within 3 seconds to remain validated.  - -Please visit our page [Securing webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#securing-webhooks) for more details. -  - -**Is there anything that would immediately invalidate my webhook URL?** - -If one of the following occurs, we will immediately mark your webhook as invalid: - -* The server responds to a CRC with an incorrect token. In this case, our system will not [retry](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#retries) to send you the activity. -* The webhook URL has an incorrect certificate configured. In this case, our system will not [retry](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#retries) to send you the activity. -* Your server returning a non-2XX, non-4XXX, non-5XXX response code. -* You specify the use of gzip without actually sending it. -* You do not specify the use of gzip, but actually send it in the response. -   - -**Will I get duplicate activities if subscribed to users that are interacting with each other?** - -Yes.  If your web app has active subscriptions for User A and User B, and User A mentions User B in a Post, there will be two POST activities sent to the registered webhook.  Each activity will have an indicator of "for\_user\_id" to show which subscription the activity belongs to. -  - -**When I make a subscription to my webhook, can I replace the `/all/` portion of the following endpoint with other account activity data objects to limit the activities the API delivers? **`POST https://api.x.com/1.1/account_activity/all/:env_name/subscriptions.json` - -No, this is not possible. As it currently stands, we only have the `/all/` product available. -  - -**Is there any way of using the Account Activity API without requesting Direct Messages permissions from users? ** - -At this point, Direct Messages permissions are required because there is no way to 'filter out' the Direct Messages activities for this API.  -  - -**Is there a sandbox version of the Account Activity API?** - -Yes, we offer a sandbox option for testing. Our sandbox option is limited to a single webhook with a limit of a maximum of 15 subscriptions. You can read more about the sandbox option in [our documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity).  - - -**Is it possible to use the Account Activity API to get Retweets of Posts that mention subscribed users? ** - -Unfortunately, this is not part of the activities delivered with this API. For this, we suggest using the Streaming API instead.  -  - -**What are the possible activity types that are represented by a tweet\_create\_event?** - -A tweet\_create\_event payload will be sent: - -If the subscription user does any of the following actions: - -* Creates a Post -* Retweets -* Replies to a Post - -If another user: - -* @mentions* the subscription user -* Quotes a Tweet created by the subscription user  - -*Note: The Account Activity API only delivers events when the subscription user would receive a notification from X and could see the event publicly.  This means, If the mentioned account (@userA) follows the protected account (@userB) then UserA will get a notification UserB mentioned them. If UserA is not following UserB (and approved by UserB) UserA will not get a notification, and therefore a tweet\_create\_event would not be sent via AAA if @userA had a subscription. - -**If a blocked user mentions my subscribed user, how can I identify this?** - -You will see a boolean field \`user\_has\_blocked\` on the top level of the json response, set to either “true” or “false". This field will only be exposed on Post mentions.  - -Enterprise - -**How can I add my app to an allowlist or check if my app is already on the allowlist?** - -To manage the [X apps](/resources/fundamentals/developer-apps) that you have added to an allowlist for access via the Enterprise APIs, please reach out to your account manager with your app ID. You can find your app ID by navigating to the ["Apps"](/resources/fundamentals/developer-apps) page in the [Developer Console](/resources/fundamentals/developer-portal). -  - -**If I have access to three webhooks, can I use three webhooks for each of the apps that I have registered for enterprise use?** - -The webhook limit is set on the account level, not the app level. If you have access to three webhooks and two apps registered for enterprise use, you can use two webhooks on one app and the third on the other app, but not three on each app.  - - -**Can I specify which types of events will be redelivered using the Account Activity Replay API?** - -The types of events to replay cannot be specified. All events delivered during the date and time window specified will be replayed.  - - -**Will there be any retries if my application fails to ingest an Account Activity Replay API event?** - -No, there will not be any retries. If an application fails to ingest an event sent by the Account Activity Replay API, another Replay job can be submitted for the same time period to attempt redelivery of any missed Replay events.  - - -**What should I do when I receive a partial success completion event?** - -We suggest making note of the timestamps for the events that were received and requesting another Replay job for the events that were missed.  - - -**How many Account Activity Replay API jobs can I have running at a time?** - -Only one Account Activity Replay API job per webhook may be running at a time.  - - -**How can I differentiate Account Activity Replay API events from real-time production events as they are delivered to my webhook?** - -Since the Account Activity Replay API will always deliver events from the past, events can be differentiated from real-time production events based on the event’s timestamp.  - - -**How soon can I start using the Account Activity Replay API to redeliver an activity my application dropped or missed?** - -An activity becomes available for redelivery about 10 minutes after it was created.  - -### Error troubleshooting guide - -#### Code 32 - -This error generally means that something is either malformed in the request, headers, authorization, or url that you are specifying. This is not an Account Activity API error, it’s an authorization error and X isn’t getting the proper Oauth setup or url. - -* **Enterprise** \- Make sure the consumer keys and access tokens you are using belong to a [X app](/resources/fundamentals/developer-apps) that has been registered for use of Enterprise products. If you don't have your consumer keys and access tokens, or need to add your X app to the allowlist, please reach out to your account manager.  - -* If authenticating with user context, make sure you have properly [authorized your request](/resources/fundamentals/authentication#authorizing-a-request) with the proper `oauth nonce`, `oauth_signature`, and `oauth_timestamp`. - -* Make sure that your access tokens have the proper permission level. - * When on the 'Keys and tokens' tab in the [app dashboard](/resources/fundamentals/developer-apps), please make sure that your access tokens have the 'Read, write, and direct messages' [permission level](/resources/fundamentals/developer-apps#app-permissions).  - * If the tokens' permission level is set to anything less than this, please navigate to the 'Permissions' tab, adjust the access permission to 'Read, write, and direct messages', then regenerate your access tokens and secret from the 'Keys and tokens' tab. - -* Make sure that your URL is formed properly. - * Please keep in mind that `:env_name` is case sensitive. -   - -#### Code 200 - Forbidden - -* **Premium** \- Make sure that you have an approved [developer account](/resources/fundamentals/developer-portal) before you try to make a request to the API. You also must use the proper :env_name in the request, which you can setup on the [dev environments](/resources/fundamentals/developer-portal) page. - -* **Enterprise** \- Make sure that your account manager has set you up with access to the Account Activity API. -* Make sure you have set up your URI properly. This error can trigger if you have entered the incorrect URI in your request. -   - -#### Code 214 - Webhook URL does not meet the requirements. - -* Please make sure that you are using https. -* Your webhook URL could be malformed. -* Learn more about how to set up your webhook URL under the [Develop webhook consumer app](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#3-develop-webhook-consumer-app) section on [Getting started with webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks) page. -   - -#### Code 214 - High latency on CRC GET request. Your webhook should respond in less than 3 seconds. - -* This means that your server is slow. Make sure that you are responding to the CRC within 3 seconds. -   - -#### Code 214 - Non-200 response code during CRC GET request (i.e. 404, 500, etc). - -* Your server is down. Make sure that your server is running properly. -   - -#### Code 214 - Too many resources already created. - -* **Enterprise** \- You have already used all of your webhooks. Use the [GET webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) endpoint with each of your registered apps to identify where your webhooks are distributed.  - - - -#### Code 261 - Application cannot perform write actions. - -* The app that you are using with the API does not have the proper [permission level](/resources/fundamentals/developer-apps#app-permissions) set for its access token and access token secret. Please navigate to the 'Keys and tokens' tab on the [X apps](/resources/fundamentals/developer-apps) dashboard and check the permission levels assigned to your access token and access token secret. If it is set to anything other than 'Read, write and Direct Messages,' then you are going to have to adjust the settings under the 'Permission' tab and regenerate your access token and access token secret to apply the new settings. -* Alternatively, you are trying to register a webhook using app-only authentication, which is not supported. Please authenticate with user context instead as noted in the API reference sections for registering a webhook for [Enterprise Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks). - - -## Account Activity API Reference Index - -| | | -| :--- | :--- | -| **Purpose** | Enterprise | -| Registers a webhook URL / Generates a webhook_id | [POST
webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) | -| Returns all webhook URLs and their statuses | [GET
webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) | -| Manually triggers a challenge response check | [PUT
webhooks/:webhook_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id) | -| Subscribes an application to an account's events | [POST
webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all) | -| Returns a count of currently active subscriptions | [GET
subscriptions/count](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | -| Check to see if a webhook is subscribed to an account | [GET
webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all) | -| Returns a list of currently active subscriptions | [GET
webhooks/:webhook_id/subscriptions/all/list](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | -| Deletes the webhook | [DELETE
webhooks/:webhook_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id) | -| Deactivates a subscription using 3-legged OAuth (DEPRECATED) | [DELETE
webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) | -| Deactivates a subscription using application-only OAuth | [DELETE
webhooks/:webhook\_id/subscriptions/:user\_id/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json) | -| Redelivers activities to a webhook | [POST
replay/webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) | - - -### Enterprise Account Activity API - -#### POST account_activity/webhooks[](#post-account-activity-webhooks "Permalink to this headline") - -Registers a new webhook URL for the given application context. The URL will be validated via CRC request before saving. In case the validation failed, returns comprehensive error message to the requester. - -The number of allowed webhooks is determined by billing package. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (user context - all consumer and access tokens) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 15 | -| Support for Tweet edits | All Tweet objects will include Tweet edit metadata describing the Tweet's edit history. See the ["Tweet edits" fundamentals](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) page for more details. | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| url (required) | Encoded URL for the callback endpoint. | - -### Example Request[](#example-request "Permalink to this headline") - - $ curl --request POST - --url 'https://api.x.com/1.1/account_activity/webhooks.json?url=https%3A%2F%2Fyour_domain.com%2Fwebhooks%2Ftwitter%2F0' - --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"' - -### HTTP Responses[](#http-responses "Permalink to this headline") - -| HTTP Code | Message | -| :--- | :--- | -| 200 | Webhook URL is registered to the provided application | -| 403 | There is an error with your request. See error messages section below. | - -### Example Response - Success[](#example-response-success "Permalink to this headline") -```json -_HTTP 200_ - - { - "id": "1234567890", - "url": "https://your_domain.com/webhook/twitter/0", - "valid": true, - "created_at": "2016-06-02T23:54:02Z" - } -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 214 | Webhook URL does not meet the requirements. | -| 214 | Too many resources already created. | -| 214 | Webhook URL does not meet the requirements. Invalid CRC token or json response format. | -| 214 | High latency on CRC GET request. Your webhook should respond in less than 3 seconds. | -| 214 | Non-200 response code during CRC GET request (i.e. 404, 500, etc). | - -_HTTP 403_ -```json - { - "errors": [ - { - "code": 214, - "message": "Too many resources already created." - } - ] - } -``` -#### GET account_activity/webhooks[](#get-account-activity-webhooks "Permalink to this headline") - -Returns all URLs and their statuses for the given application. - -We mark a URL as invalid if it fails the daily validation check. In order to re-enable the URL, call the update endpoint. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (application only - bearer token) | -| Rate Limited | Yes | -| Requests / 15-min window (application auth) | 15 | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request GET - --url https://api.x.com/1.1/account_activity/webhooks.json - --header 'authorization: Bearer TOKEN' -``` -### Example Response[](#example-response "Permalink to this headline") - -_HTTP 200 OK_ -```json - [ - { - "id": "1234567890", - "url": "https://your_domain.com/webhook/twitter/0", - "valid": true, - "created_at": "2016-06-02T23:54:02Z" - } - { - "id": "2468013579", - "url": "https://your_domain2.com/webhook/twitter/0", - "valid": true, - "created_at": "2016-06-04T22:31:29Z" - } - ] -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 99 | You don’t have access to this resource. | - -#### PUT account\_activity/webhooks/:webhook\_id[](#put-account-activity-webhooks-webhook-id "Permalink to this headline") -Triggers the challenge response check (CRC) for the given webhook's URL. If the check is successful, returns 204 and reenables the webhook by setting its status to `valid`. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (user context - all consumer and access tokens) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 15 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") -```json - $ curl --request PUT - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json - --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"' -``` -### Response[](#response "Permalink to this headline") - -_HTTP 204 OK_ -``` - { } -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 34 | Webhook does not exist or is associated with a different X application. | -| 214 | Webhook URL does not meet the requirements. | -| 214 | Webhook URL does not meet the requirements. Invalid CRC token or json response format. | -| 214 | High latency on CRC GET request. Your webhook should respond in less than 3 seconds. | -| 214 | Non-200 response code during CRC GET request (i.e. 404, 500, etc). | - -#### POST account\_activity/webhooks/:webhook\_id/subscriptions/all[](#post-account-activity-webhooks-webhook-id-subscriptions-all "Permalink to this headline") - -Subscribes the provided application to all events for the provided user context for all message types. After activation, all events for the requesting user will be sent to the application’s webhook via POST request. - -Subscriptions are currently limited based on your account configuration. If you have a need to add more subscriptions, please contact your account manager. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribing user's access token) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 500 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request POST - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json - --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"' -``` -### Example Response - Success[](#example-response-success "Permalink to this headline") - -_HTTP 204 NO CONTENT_ -``` - {} -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 34 | Webhook does not exist or is associated with a different X application. | -| 348 | Client application is not permitted to access this user's webhook subscriptions. | - -#### GET account_activity/subscriptions/count[](#get-account-activity-subscriptions-count "Permalink to this headline") - -Returns the count of subscriptions that are currently active on your account. Note that the /count endpoint requires application-only OAuth, so that you should make requests using a bearer token instead of user context. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/subscriptions/count.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | HTTP response code | -| Requires Authentication | Yes (application only - bearer token) | -| Rate Limited | Yes | -| Requests / 15-min window (application auth) | 15 | - -### HTTP Response Codes[](#http-response-codes "Permalink to this headline") - -| | | -| :--- | :--- | -| Code | Message | -| 200 | Success. A count of subscriptions for the requested webhook will be returned. | -| 401 | Your application does not have permission to view subscriptions for the specified webhook. | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request GET - --url https://api.x.com/1.1/account_activity/subscriptions/count.json - --header 'authorization: Bearer TOKEN' -``` -### Example Response - Success[](#example-response-success "Permalink to this headline") - -_HTTP 200_ -```bash - { - "account_name":"my-account", - "subscriptions_count_all":"1", - "subscriptions_count_direct_messages":"0", - "provisioned_count":"50" - } -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 32 | Could not authenticate you. | - -_HTTP 401_ -```abash - { - "errors": [ - { - "code": 32, - "message": "Could not authenticate you." - } - ] - } -``` -#### GET account\_activity/webhooks/:webhook\_id/subscriptions/all[](#get-account-activity-webhooks-webhook-id-subscriptions-all "Permalink to this headline") - -Provides a way to determine if a webhook configuration is subscribed to the provided user’s events. If the provided user context has an active subscription with provided application, returns 204 OK. If the response code is not 204, then the user does not have an active subscription. See HTTP Response code and error messages below for details. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribing user's access token) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 500 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") - - $ curl --request GET - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json - --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"' - -### Example Response - Success[](#example-response-success "Permalink to this headline") - -_HTTP 204 NO CONTENT_ -``` - { } -``` -#### GET account\_activity/webhooks/:webhook\_id/subscriptions/all/list[](#get-account-activity-webhooks-webhook-id-subscriptions-all-list "Permalink to this headline") - -Returns a list of the current All Activity type subscriptions for the specified webhook. Note that the /list endpoint requires application-only OAuth, so requests should be made using a bearer token instead of user context. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all/list.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | HTTP response code | -| Requires Authentication | Yes (application only - bearer token) | -| Rate Limited | Yes | -| Requests / 15-min window (application auth) | 50 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### HTTP Response Codes[](#http-response-codes "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 200 | Success. A list of subscriptions for the requested webhook will be returned. | -| 401 | Your application does not have permission to view subscriptions for the specified webhook. | - -### Example Request[](#example-request "Permalink to this headline") - - $ curl --request GET - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all/list.json - --header 'authorization: Bearer TOKEN' - -### Example Response - Success[](#example-response-success "Permalink to this headline") - -_HTTP 200_ -```bash - { - "webhook_id": "1234567890", - "webhook_url": "https://your_domain.com/webhook/twitter/0", - "application_id": "11231812", - "subscriptions": [{ - "user_id": "20212306" - }] - } -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 32 | Could not authenticate you. | - -_HTTP 401_ -```bash - { - "errors": [ - { - "code": 32, - "message": "Could not authenticate you." - } - ] - } -``` -#### DELETE account\_activity/webhooks/:webhook\_id[](#delete-account-activity-webhooks-webhook-id "Permalink to this headline") - -Removes the webhook from the provided application's configuration. The webhook ID can be accessed by making a call to GET /1.1/account_activity/webhooks. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (user context - all consumer and access tokens) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 15 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request DELETE - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json - --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"' -``` -### Response[](#response "Permalink to this headline") - -_HTTP 204 OK_ -``` - { } -``` -#### DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all (DEPRECATED)[](#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated- "Permalink to this headline") - -Deactivates subscription(s) for the provided user context and application. After deactivation, all events for the requesting user will no longer be sent to the webhook URL. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribed user's access token) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 500 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request DELETE - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json - --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBED_USER'S_ACCESS_TOKEN", oauth_version="1.0"' -``` - Example Request -``` - { } -``` -#### DELETE /account\_activity/webhooks/:webhook\_id/subscriptions/:user_id/all.json[](#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json "Permalink to this headline") - -Deactivates subscription for the specified webhook and user id. After deactivation, all events for the requesting user will no longer be sent to the webhook URL. Note, that this endpoint requires application-only OAuth, so requests should be made using a bearer token instead of user context. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (application only - bearer token) | -| Rate Limited | Yes | -| Requests / 15-min window | 500 | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request DELETE - --url https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json - --header 'authorization: Bearer TOKEN' -``` - -### Response[](#response "Permalink to this headline") - -_HTTP 204 NO CONTENT_ - -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 404 | Sorry, that page does not exist. - This often occurs when the specified user id is not actually subscribed. | - - -### Replay API - -**POST /1.1/account\_activity/replay/webhooks/:webhook\_id/subscriptions/all.json [¶](#post-1-1-account-activity-replay-webhooks-webhook-id-subscriptions-all-json- "Permalink to this headline")** - -Submits a request to retrieve activities from up to the past five days from all subscriptions present during the date and time windows specified in the request. If your webhook has active user subscriptions, you will concurrently receive those events as well. Note: We do perform a CRC before delivering replay events. - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | /1.1/account\_activity/replay/webhooks/:webhook\_id/subscriptions/all.json?from\_date=yyyymmddhhmm&to\_date=yyyymmddhhmm | -| **Response Format** | JSON | -| **Requires Authentication** | Yes (application only - bearer token) | -| **Rate Limit** | 5 requests per 15 minutes. There is currently no maximum on the number of replay jobs that can requested. | -| **from_date** | The oldest (starting) UTC timestamp from which the events will be provided, must be in 'yyyymmddhhmm' format. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute). Valid times must be within the last 5 days, UTC time, and no more recent than 31 minutes before the current point in time. It's recommended that the from\_date and to\_date should be within ~2 hours. | -| **to_date** | The latest (ending) UTC timestamp to which the event will be provided, must be in 'yyyymmddhhmm' format. Timestamp is in minute granularity and is exclusive (i.e. 12:30 does not include the 30th minute of the hour). Valid times must be within the last 5 days, UTC time, and no more recent than 10 minutes before the current point in time. | - - - -#### Responses - -The following responses may be returned by the API. Most error codes are returned with a string including additional details in the body. For non-200 responses, you should resolve the error and try again. - -| Status | Text | Error Code | Description | Message | -| :--- | :--- | :--- | :--- | :--- | -| 202 | Accepted | N/A | The request was successful and the activities will be sent. | N/A | -| 400 | Bad Request | 214 | Webhook has been marked as invalid. | Webhook is marked invalid and requires a CRC check. | -| 400 | Bad Request | 357 | Query parameter is missing. | : queryParam is required. | -| 400 | Bad Request | 358 | Route or query parameter is malformed. | Unable to parse parameter. | -| 400 | Bad Request | 360 | Route parameter is negative. | webhook_id: \[\] is not greater than or equal to 0. | -| 400 | Bad Request | 368 | from\_date or to\_date is not in the past. | : \[<field_value>\] is not in the past. | -| 400 | Bad Request | 356 | from\_date must be before to\_date. | from\_date must be before to\_date. | -| 400 | Bad Request | 356 | from_date must be within the past 5 days. | from_date must be within the past 5 days. | -| 401 | Unauthorized | 32 | HTTP authentication failed due to 3-legged auth provided. | Invalid authentication method. Please use application-only authentication. | -| 401 | Unauthorized | 61 | Client is not permitted to request this method. | Client is not permitted to request this method. | -| 403 | Forbidden | 200 | Client does not have an enterprise account with Replay enabled. | Account Activity API enterprise account with replay is required. Please confirm you have an enterprise account and replay is enabled. | -| 404 | Not Found | 34 | Non-existing webhook\_id; webhook\_id-application_id mismatch. | Webhook does not exist or is associated with a different X application. | -| 409 | Conflict | 355 | There is a request in flight and it will need to finish processing before making another. | A replay job is already in progress for this webhook. | -| 429 | Too Many Requests | 88 | Rate limited (hit limit of the number of requests per time period) | Too many requests. Please back off your API request rate. | -| 500 | Internal Server Error | 0 | Internal server error. | Internal server error. | -| 503 | Service Unavailable | 67 | One or more dependent services at X is unavailable. | X server error. Retry using an exponential backoff pattern. | - - - -#### "Job completed successfully” message - -Once your job successfully completes, Account Activity Replay API will deliver the following job completion event. Once you receive this event, the job has finished running and another can be submitted. -```json -{ - "replay\_job\_status": { - "webhook_id": "1234577122340233217", - "job_state": "Complete", - "job\_state\_description": "Job completed successfully" - "job_id": "1095098195724558337" - } -} -``` -#### "Job failed to complete" message - -In the event your job does not complete successfully, we will return the following message encouraging you to retry your Replay job. Once you receive this event, the job has finished running and another can be submitted. -```json -{ - "replay\_job\_status": { - "webhook_id": "123451374207332352", - "job_state": "Incomplete", - "job\_state\_description": "Job failed to deliver all events, please retry your replay job", - "job_id": "1093226942650736640" - } -} -``` -#### Example curl request -```bash - curl --request POST --url 'https://api.x.com/1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm' - --header 'authorization: Bearer TOKEN' -``` -#### Example response - -HTTP 202 -```bash -{ - "job_id": "1234567890", - "created_at": "2016-06-02T23:54:02Z" -} -``` diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/data-dictionary.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/data-dictionary.mdx deleted file mode 100644 index 6457e96f9..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/data-dictionary.mdx +++ /dev/null @@ -1,4999 +0,0 @@ ---- -title: "Data dictionary: Enterprise" -description: "Interested in learning more about how the enterprise data formats map to the X API v2 format?" -sidebarTitle: Data dictionary -keywords: ["enterprise data dictionary", "GNIP data dictionary", "enterprise data format", "data dictionary enterprise", "enterprise objects"] ---- - ->Check out our comparison guides: -> ->* [Native Enriched compared to X API v2](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2) ->* [Activity Streams compared to X API v2](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) - -## X API: Enterprise data dictionary -### Introduction - -`Enterprise` - -Posts are the basic atomic building block of all things X. All X APIs that return Posts provide that data encoded using JavaScript Object Notation (JSON). JSON is based on key-value pairs, with named attributes and associated values. Post objects retrieved from the API include a X User's "status update" but Retweets, replies, and quote Tweets are all also Post objects.  If a Post is related to another Post, as a Retweet, reply or quote Tweet, each will be identified or embedded into the Post object.  Even the simplest Post in the native X data format, will have nested JSON objects to represent the other attributes of a Post, such as the author, mentioned users, tagged place location, hashtags, cashtag symbols, media or URL links.  When working with X data, this is an important concept to understand. The format of the Post data you will receive from the X API depends on the type of Post received, the X API you are using, and the format settings. - -Enterprise endpoints that return Post objects have been updated to provide the metadata needed to understand the Post's edit history. Learn more about these metadata on the ["Edit Posts" fundamentals](/x-api/fundamentals/edit-posts) page. - -In native X format, the JSON payload will include of ‘root-level’ attributes, and nested JSON objects (which are represented here with the `{}` notation): - -```JSON -{ - "created_at": "Fri Feb 14 19:00:55 +0000 2020", - "id_str": "1228393702244134912", - "text": "What did the developer write in their Valentine’s card?\n \nwhile(true) {\n I = Love(You); \n}", - "entities": { - "hashtags": [], - "symbols": [], - "user_mentions": [], - "urls": [] - }, - "user": { - "entities": { - "url": {} - } - }, - "place": {} -} -``` - -### Available data formats - ->Please note: It is highly recommended to use the [Enriched Native](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-tweet-object) format for enterprise data APIs.  -> ->* The Enriched Native format includes all new metadata since 2017, such as [poll metadata](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#poll-metadata), and additional metrics such as reply\_count and quote\_count. -> ->* Activity Streams format has not been updated with new metadata or enrichments since the [character update](https://blog.x.com/official/en_us/topics/product/2017/Giving-you-more-characters-to-express-yourself.html) in 2017. - - -Enterprise data APIs deliver data in two different formats.  The enterprise format closest to the standard v1.1 native format is Native Enriched.  The legacy enterprise data format is Activity Streams, orignially implimented and used by Gnip as a normalized format across X and other social media data providers at the time. While this format is still available, X has only invested new features and developments on the native enriched format since 2017. - -The enriched native format is exactly how it sounds, it includes native X objects as well as additional enrichments avialable for enterprise data products such as URL unwinding metadata, profile geo, poll metadata and additional engagement metrics.   - -* [Expanded and enhanced URLs enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#expanded-and-enhanced-urls) -* [Matching rules enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#matching-rules) -* [Poll metadata enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#poll-metadata) -* [Profile geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) - -#### Object comparison per data format - -Whatever your X use case, understanding what these JSON-encoded Post objects and attributes _represent_ is critical to successfully finding your data signals of interest. To help in that effort, there are a set of pages dedicated to each object in each data format_._ - -Reflecting the JSON hierarchy above, here are links to each of these objects: - -| Native Enriched | Activity Streams | -| :--- | :--- | -| [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-tweet-object) Post object | [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#post-object) Activity object | -| [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object) User object | [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object) Actor object | -| [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-entities) Entities object | [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-entities) X entities object | -| [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-extended-entities) Extended entities object | [Link]/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-extended-entities X extended entitites object | -| [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-geo-objects) Geo object | [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-geo-objects) Location object | -| n/a | [Link](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#gnip-object) Gnip object | - -### Parsing best-practices - -* X JSON is encoded using UTF-8 characters. -* Parsers should tolerate variance in the ordering of fields with ease. It should be assumed that Post JSON is served as an unordered hash of data. -* Parsers should tolerate the addition of 'new' fields.  -* JSON parsers must be tolerant of ‘missing’ fields, since not all fields appear in all contexts. -* It is generally safe to consider a nulled field, an empty set, and the absence of a field as the same thing - -## Enterprise Native Enriched data objects - -### Native Enriched Tweet object - ->Interested in learning more about how the Native Enriched data format maps to the X API v2 format? -> ->Check out our comparison guide: [Native Enriched compared to X API v2](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2) - -#### Post Object - -When using enterprise data products, you will notice that much of the data dictionary is similar to the native format of Post data, with some additional enriched metadata.  The base level of the native enriched format uses much of the same object names as the [X API v1.1 data format](https://developer.x.com/en/docs/x-api/v1/data-dictionary/overview.html).  The Post object has a long list of ‘root-level’ attributes, including fundamental attributes such as `id`, `created_at`, and `text`. Post objects will also have nested objects to include the `user`, `entities`, and `extended_entities`. Post objects will also have other [nested Post objects](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#nested-post-objects) such as retweeted\_status, quoted\_status and extended\_tweet.  The native enriched format will additionally have a matching\_rules object. - -##### X Data Dictionary - -Below you will find the data dictionary for these ‘root-level’ attributes, as well as links to child object data dictionaries. - -| Attribute | Type | Description | -| :--- | :--- | :--- | -| created_at | String | UTC time when this Post was created. Example:

"created_at": "Wed Oct 10 20:19:24 +0000 2018" | -| id | Int64 | The integer representation of the unique identifier for this Post. This number is greater than 53 bits and some programming languages may have difficulty/silent defects in interpreting it. Using a signed 64 bit integer for storing this identifier is safe. Use **`id_str`** to fetch the identifier to be safe. See [X IDs](/resources/fundamentals/x-ids) for more information. Example:

"id":1050118621198921728 | -| id_str | String | The string representation of the unique identifier for this Post. Implementations should use this rather than the large integer in **`id`**. Example:

"id_str":"1050118621198921728" | -| text | String | The actual UTF-8 text of the status update. See [X-text](https://github.com/twitter/twitter-text/blob/master/rb/lib/twitter-text/regex.rb) for details on what characters are currently considered valid. Example:

"text":"To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin t… https://t.co/MkGjXf9aXm" | -| source | String | Utility used to post the Post, as an HTML-formatted string. Posts from the X website have a source value of **`web`**.

Example:

"source":"X Web Client" | -| truncated | Boolean | Indicates whether the value of the **`text`** parameter was truncated, for example, as a result of a retweet exceeding the original Post text length limit of 140 characters. Truncated text will end in ellipsis, like this **`...`** Since X now rejects long Posts vs truncating them, the large majority of Posts will have this set to **`false`** . Note that while native retweets may have their toplevel **`text`** property shortened, the original text will be available under the **`retweeted_status`** object and the **`truncated`** parameter will be set to the value of the original status (in most cases, **`false`** ). Example:

"truncated":true | -| in\_reply\_to\_status\_id | Int64 | _Nullable._ If the represented Post is a reply, this field will contain the integer representation of the original Post's ID. Example:

"in\_reply\_to\_status\_id":1051222721923756032 | -| in\_reply\_to\_status\_id_str | String | _Nullable._ If the represented Post is a reply, this field will contain the string representation of the original Post's ID. Example:

"in\_reply\_to\_status\_id_str":"1051222721923756032" | -| in\_reply\_to\_user\_id | Int64 | _Nullable._ If the represented Post is a reply, this field will contain the integer representation of the original Post's author ID. This will not necessarily always be the user directly mentioned in the Post. Example:

"in\_reply\_to\_user\_id":6253282 | -| in\_reply\_to\_user\_id_str | String | _Nullable._ If the represented Post is a reply, this field will contain the string representation of the original Post's author ID. This will not necessarily always be the user directly mentioned in the Post. Example:

"in\_reply\_to\_user\_id_str":"6253282" | -| in\_reply\_to\_screen\_name | String | _Nullable._ If the represented Post is a reply, this field will contain the screen name of the original Post's author. Example:

"in\_reply\_to\_screen\_name":"xapi" | -| user | [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object) | The user who posted this Post. See User data dictionary for complete list of attributes.

Example highlighting select attributes:

\{ "user": \
"id": 6253282,
"id_str": "6253282",
"name": "X API",
"screen_name": "API",
"location": "San Francisco, CA",
"url": "https://developer.x.com",
"description": "The Real X API. Tweets about API changes, service issues and our Developer Platform. Don't get an answer? It's on my website.",
"verified": true,
"followers_count": 6129794,
"friends_count": 12,
"listed_count": 12899,
"favourites_count": 31,
"statuses_count": 3658,
"created_at": "Wed May 23 06:01:13 +0000 2007",
"utc_offset": null,
"time_zone": null,
"geo_enabled": false,
"lang": "en",
"contributors_enabled": false,
"is_translator": false,
"profile\_background\_color": "null",
"profile\_background\_image_url": "null",
"profile\_background\_image\_url\_https": "null",
"profile\_background\_tile": null,
"profile\_link\_color": "null",
"profile\_sidebar\_border_color": "null",
"profile\_sidebar\_fill_color": "null",
"profile\_text\_color": "null",
"profile\_use\_background_image": null,
"profile\_image\_url": "null",
"profile\_image\_url\_https": "https://pbs.twimg.com/profile\_images/942858479592554497/BbazLO9L_normal.jpg",
"profile\_banner\_url": "https://pbs.twimg.com/profile_banners/6253282/1497491515",
"default_profile": false,
"default\_profile\_image": false,
"following": null,
"follow\_request\_sent": null,
"notifications": null
}
} | -| coordinates | [Coordinates](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-geo-objects) | _Nullable._ Represents the geographic location of this Post as reported by the user or client application. The inner coordinates array is formatted as [geoJSON](http://www.geojson.org/) (longitude first, then latitude). Example:

"coordinates":
\
"coordinates":
\[
-75.14310264,
40.05701649
\],
"type":"Point"
} | -| place | [Places](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#place-data-dictionary) | _Nullable_ When present, indicates that the Post is associated (but not necessarily originating from) a Place  Example:

"place":
\
"attributes":{},
"bounding_box":
\
"coordinates":
\[\[
\[-77.119759,38.791645\],
\[-76.909393,38.791645\],
\[-76.909393,38.995548\],
\[-77.119759,38.995548\]
\]\],
"type":"Polygon"
},
"country":"United States",
"country_code":"US",
"full_name":"Washington, DC",
"id":"01fbe706f872cb32",
"name":"Washington",
"place_type":"city",
"url":"http://api.x.com/1/geo/id/0172cb32.json"
} | -| quoted\_status\_id | Int64 | This field only surfaces when the Post is a quote Tweet. This field contains the integer value Post ID of the quoted Tweet. Example:

"quoted\_status\_id":1050119905717055488 | -| quoted\_status\_id_str | String | This field only surfaces when the Post is a quote Tweet. This is the string representation Post ID of the quoted Tweet. Example:

"quoted\_status\_id_str":"1050119905717055488" | -| is\_quote\_status | Boolean | Indicates whether this is a Quoted Tweet. Example:

"is\_quote\_status":false | -| quoted_status | Post | This field only surfaces when the Post is a quote Tweet. This attribute contains the Post object of the original Post that was quoted. | -| retweeted_status | Post | Users can amplify the broadcast of Posts authored by other users by Retweeting . Retweets can be distinguished from typical Posts by the existence of a **`retweeted_status`** attribute. This attribute contains a representation of the _original_ Post that was retweeted. Note that retweets of retweets do not show representations of the intermediary retweet, but only the original Post. (Users can also unretweet a retweet they created by deleting their retweet.) | -| quote_count | Integer | _Nullable._ Indicates approximately how many times this Post has been quoted by X users. Example:

"quote_count":33

Note: This object is only available with the Premium and Enterprise tier products. | -| reply_count | Int | Number of times this Post has been replied to. Example:

"reply_count":30

Note: This object is only available with the Premium and Enterprise tier products. | -| retweet_count | Int | Number of times this Post has been retweeted. Example:

"retweet_count":160 | -| favorite_count | Integer | _Nullable._ Indicates approximately how many times this Post has been liked by X users. Example:

"favorite_count":295 | -| entities | [Entities](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-entities) | Entities which have been parsed out of the text of the Post. Additionally see [Entities in X Objects](https://developer.x.com/en/docs/x-api/v1/data-dictionary/object-model/entities) . Example:

"entities":
\
"hashtags":\[\],
"urls":\[\],
"user_mentions":\[\],
"media":\[\],
"symbols":\[\]
"polls":\[\]
} | -| extended_entities | [Extended Entities](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-entities) | When between one and four native photos or one video or one animated GIF are in Post, contains an array 'media' metadata. This is also available in Quote Tweets. Additionally see [Entities in X Objects](https://developer.x.com/en/docs/x-api/v1/data-dictionary/object-model/extended-entities) . Example:

"entities":
\
"media":\[\]
} | -| favorited | Boolean | _Nullable._ Indicates whether this Post has been liked by the authenticating user. Example:

"favorited":true | -| retweeted | Boolean | Indicates whether this Post has been Retweeted by the authenticating user. Example:

"retweeted":false | -| possibly_sensitive | Boolean | _Nullable._ This field indicates content may be recognized as sensitive. The Post author can select within their own account preferences and choose “Mark media you post as having material that may be sensitive” so each Post created after has this flag set.

This may also be judged and labeled by an internal X support agent.

"possibly_sensitive":false | -| filter_level | String | Indicates the maximum value of the filter_level parameter which may be used and still stream this Post. So a value of **`medium`** will be streamed on **`none`**, **`low`**, and **`medium`** streams.

Example:

"filter_level": "low" | -| lang | String | _Nullable._ When present, indicates a [BCP 47](http://tools.ietf.org/html/bcp47) language identifier corresponding to the machine-detected language of the Post text, or **`und`** if no language could be detected. 

 Example:

"lang": "en" | -| edit_history | Object | Unique identifiers indicating all versions of a Post. For Posts with no edits, there will be one ID. For Posts with an edit history, there will be multiple IDs, arranged in ascending order reflecting the order of edits, with the most recent version in the last position of the array. 

The Post IDs can be used to hydrate and view previous versions of a Post.

Example:

edit_history": \
"initial\_tweet\_id": "1283764123"
"edit\_tweet\_ids": \["1283764123", "1394263866"\]
} | -| edit_controls | Object | When present, indicates how long a Post is still editable for and the number of remaining edits. Posts are only editable for the first 30 minutes after creation and can be edited up to five times. 

The Post IDs can be used to hydrate and view previous versions of a Post.

Example:

"edit_controls": \
"editable\_until\_ms": 123
"edits_remaining": 3
} | -| editable | Boolean | When present, indicates if a Post was eligible for edit when published. This field is not dynamic and won't toggle from True to False when a Post reaches its editable time limit, or maximum number of edits. The following Post features will cause this field to be false:

* Posts is promoted
* Post has a poll
* Post is a non-self-thread reply
* Post is a retweet (note that Quote Tweets are eligible for edit)
* Post is nullcast
* Community Post
* Superfollow Post
* Collaborative Post | -| matching_rules | Array of Rule Objects | Present in _filtered_ products such as X Search and PowerTrack. Provides the _id_ and _tag_ associated with the rule that matched the Post. More on matching rules [here](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#matching-rules). With PowerTrack, more than one rule can match a Post. 

Example:

"matching_rules": " \[\
"tag": "xapi emojis",
"id": 1050118621198921728,
"id_str": "1050118621198921728"
}\]" | - -##### Additional Post attributes - -X APIs that provide Posts (e.g. the GET statuses/lookup endpoint) may include these additional Post attributes: - -| Attribute | Type | Description | -| :--- | :--- | :--- | -| current\_user\_retweet | Object | _Perspectival_ Only surfaces on methods supporting the include\_my\_retweet parameter, when set to true. Details the Post ID of the user’s own retweet (if existent) of this Post. Example:

"current\_user\_retweet": \
"id": 6253282,
"id_str": "6253282"
} | -| scopes | Object | A set of key-value pairs indicating the intended contextual delivery of the containing Post. Currently used by X's Promoted Products. Example:

"scopes":\{"followers":false} | -| withheld_copyright | Boolean | When present and set to “true”, it indicates that this piece of content has been withheld due to a [DMCA complaint](http://en.wikipedia.org/wiki/Digital_Millennium_Copyright_Act) . Example:

"withheld_copyright": true | -| withheld\_in\_countries | Array of String | When present, indicates a list of uppercase [two-letter country codes](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) this content is withheld from. X supports the following non-country values for this field:

“XX” - Content is withheld in all countries “XY” - Content is withheld due to a DMCA request.

Example:

"withheld\_in\_countries": \["GR", "HK", "MY"\] | -| withheld_scope | String | When present, indicates whether the content being withheld is the “status” or a “user.”

Example:

"withheld_scope": "status" | - -##### Deprecated Attributes - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| geo | Object | **Deprecated.** _Nullable._ Use the `coordinates` field instead. This deprecated attribute has its coordinates formatted as _\[lat, long\]_, while all other Post geo is formatted as _\[long, lat\]_. | - - -#### Nested Post objects - -In several cases, a Post object will included other nested objects.  If you are working with nested objects, then that JSON payload will contain multiple Post objects, and each Post object may contain its own objects. The root-level object will contain information on the type of action taken, i.e. whether it is a Retweet or a Quote Tweet, and may also contain an object that describes the 'original' Post being shared. Extended Posts will include a nested extended object that extends beyond 140 characters, which was used to prevent breaking changes when the update was made in 2017. Each nested object dictionary is described below. - -**Retweets** - -Retweets always contain two Post objects. The 'original' Post being Retweeted is provided in a "retweeted_status" object. The root-level object encapsulates the Retweet itself, including a User object for the account taking the Retweet action and the time of the Retweet. Retweeting is an action to share a Post with your followers, and no other new content can be added. Also, a (new) location cannot be provided with a Retweet. While the 'original' Post may have geo-tagged, the Retweet "geo" and "place" objects will always be null. - -Even before the introduction of Extended Posts, the root-level "entities" object was in some cases truncated and incomplete due to the "RT @username " string being appended to Post message being Retweeted.  Note that if a Retweet gets Retweeted, the "retweet_status" will still point to the original Post, meaning the intermediate Retweet is not included. Similar behavior is seen when using x.com to 'display' a Retweet. If you copy the unique Post ID assigned to the Retweet 'action', the original Post is displayed.  - -Below is an example structure for a Retweet. Again, when parsing Retweets, it is key to parse the "retweeted_status" object for complete (original) Post message and entity metadata. - -```json -{ - "tweet": { - "text": "RT @author original message", - "user": { - "screen_name": "Retweeter" - }, - "retweeted_status": { - "text": "original message", - "user": { - "screen_name": "OriginalTweeter" - }, - "place": {}, - "entities": {}, - "extended_entities": {} - } - }, - "entities": {}, - "extended_entities": {} -} -``` - -##### Quote Tweets - -Quote Tweets are much like Retweets except that they include a new Post message. These new messages can contain their own set of hashtags, links, and other "entities" metadata. Quote Tweets can also include location information shared by the user posting the Quote Tweet, along with media such as GIFs, videos, and photos. - -Quote Tweets will contain at least two Post objects, and in some cases, three. The Post being Quoted, which itself can be a Quoted Tweet, is provided in a "quoted_status" object. The root-level object encapsulates the Quote Tweet itself, including a User object for the account taking the sharing action and the time of the Quote Tweet. - -Note that Quote Tweets can now have photos, GIFs, or videos, added to them using the 'Post' user-interface. When links to externally hosted media are included in the Quote Tweet message, the root-level "entities.urls" will describe those. Media attached to Quote Tweets will appear in the root-level "extended_entities" metadata. - -When Quote Tweets were first launched, a shortened link (t.co URL) was appended to the 'original' Post message and provided in the root-level "text" field. In addition, metadata for that t.co URL was included in the root-level 'entities.urls' array. In May 2018, we changed this so that the shortened t.co URL to the quoted Tweet _will not be included _in the root-level "text" field. Second, the metadata for the quoted Tweet_ will not be included_ in the "entities.urls" metadata. Instead, URL metadata for the quoted Tweet will be in a new "quoted\_status\_permalink" object on the root-level (or top-level), so at the same level of the "quoted_status" object. - -Below is an example structure for a Quote Tweet using this original formatting.  - -```json -{ - "created_at": "Tue Feb 14 19:30:06 +0000 2017", - "id_str": "831586333415976960", - "text": "Definitely quotable! https:\/\/t.co\/J1LKrbHpWR", - "user": { - "screen_name": "happycamper" - }, - "quoted_status_id_str": "831569219296882688", - "quoted_status": { - "created_at": "Tue Feb 14 18:22:06 +0000 2017", - "id_str": "831569219296882688", - "text": "This is a test of the tweeting system \ud83d\ude0e to update #supportdocs @twitterboulder here: https:\/\/t.co\/NRq9UrSzm0", - "user": { - "screen_name": "furiouscamper", - }, - "place": { - "id": "9a974dfc8efb32a0", - }, - "entities": { - "hashtags": [{ - "text": "supportdocs", - }], - "urls": [{ - }], - "user_mentions": [{ }], - "symbols": [] - }, - }, - "is_quote_status": true, - "entities": {}, - "matching_rules": [{}] -} -``` -```json -{ - "created_at": "Fri Jan 04 18:47:16 +0000 2019", - "id_str": "1081260794069671936", - "text": "Quote test https://t.co/CE4m1qs3NJ", - "user": { - "screen_name": "furiouscamper" - }, - "place": null, - "quoted_status_id_str": "1079578364904648705", - "quoted_status": { - "created_at": "Mon Dec 31 03:21:54 +0000 2018", - "id_str": "1079578364904648705", - "text": "AHHHHH", - "user": { - "screen_name": "infinite_scream" - }, - "place": null, - "is_quote_status": false, - "quote_count": 1, - "reply_count": 0, - "retweet_count": 3, - "favorite_count": 6, - "entities": { - "hashtags": [], - "urls": [], - "user_mentions": [], - "symbols": [] - } - }, - "quoted_status_permalink": { - "url": "https://t.co/CE4m1qs3NJ", - "expanded": "https://x.com/infinite_scream/status/1079578364904648705", - "display": "x.com/infinite_screa…" - }, - "is_quote_status": true, - "quote_count": 0, - "reply_count": 0, - "retweet_count": 0, - "favorite_count": 1, - "entities": {} -} -``` - -##### Extended Posts - -JSON that describes _Extended Posts_ was introduced when 280-character Posts were launched in November 2017. Post JSON was extended to encapsulate these longer messages, while not breaking the thousands of apps parsing these fundamental X objects. To provide full backward compatibility, the original 140-character 'text' field, and the entity objects parsed from that, were retained. In the case of Posts longer than 140 characters, this root-level 'text' field would become truncated and thus incomplete. Since the root-level 'entities' objects contain arrays of key metadata parsed from the 'text' message, such as included hashtags and links, these collections would be incomplete. For example, if a Post message was 200 characters long, with a hashtag included at the end, the legacy root-level 'entities.hashtags' array would not include it.  - -A new 'extended\_tweet' field was introduced to hold the longer Post messages and complete entity metadata. The "extended\_tweet" object provides the "full\_text" field that contains the complete, untruncated Post message when longer than 140 characters. The "extended\_tweet" object also contains an "entities" object with complete arrays of hashtags, links, mentions, etc. - -Extended Posts are identified with a root-level "truncated" boolean. When true ("truncated": true), the "extended_tweet" fields should be parsed instead of the root-level fields. - -Note in the JSON example below that the root-level "text" field is truncated and the root-level "entities.hashtags" array is empty even though the Post message includes three hashtags. Since this is an Extended Post, the "truncated" field is set to true, and the "extended\_tweet" object provides complete "full\_text" and "entities" Post metadata. - -```json -{ - "created_at": "Thu May 10 17:41:57 +0000 2018", - "id_str": "994633657141813248", - "text": "Just another Extended Tweet with more than 140 characters, generated as a documentation example, showing that [\"tru… https://t.co/U7Se4NM7Eu", - "display_text_range": [0, 140], - "truncated": true, - "user": { - "id_str": "944480690", - "screen_name": "FloodSocial" - }, - "extended_tweet": { - "full_text": "Just another Extended Tweet with more than 140 characters, generated as a documentation example, showing that [\"truncated\": true] and the presence of an \"extended_tweet\" object with complete text and \"entities\" #documentation #parsingJSON #GeoTagged https://t.co/e9yhQTJSIA", - "display_text_range": [0, 249], - "entities": { - "hashtags": [{ - "text": "documentation", - "indices": [211, 225] - }, { - "text": "parsingJSON", - "indices": [226, 238] - }, { - "text": "GeoTagged", - "indices": [239, 249] - }] - } - - }, - "entities": { - "hashtags": [] - } -} -``` - -### Native Enriched User object - -The User object contains X User account metadata that describes the X User referenced.  - -#### User Data Dictionary - -| Attribute | Type | Description | -| :--- | :--- | :--- | -| id | Int64 | The integer representation of the unique identifier for this User. This number is greater than 53 bits and some programming languages may have difficulty/silent defects in interpreting it. Using a signed 64 bit integer for storing this identifier is safe. Use `id_str` to fetch the identifier to be safe. See [X IDs](/resources/fundamentals/x-ids) for more information. Example:

"id": 6253282 | -| id_str | String | The string representation of the unique identifier for this User. Implementations should use this rather than the large, possibly un-consumable integer in `id`. Example:

"id_str": "6253282" | -| name | String | The name of the user, as they’ve defined it. Not necessarily a person’s name. Typically capped at 50 characters, but subject to change. Example:

"name": "API" | -| screen_name | String | The screen name, handle, or alias that this user identifies themselves with. screen_names are unique but subject to change. Use `id_str` as a user identifier whenever possible. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names. Example:

"screen_name": "api" | -| location | String | _Nullable_ . The user-defined location for this account’s profile. Not necessarily a location, nor machine-parseable. This field will occasionally be fuzzily interpreted by the Search service. Example:

"location": "San Francisco, CA" | -| derived | Arrays of Enrichment Objects | Enterprise APIs only Collection of Enrichment metadata derived for user. Provides the [_Profile Geo_](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) Enrichment metadata. See referenced documentation for more information, including JSON data dictionaries. Example:

"derived":"locations": \["country":"United States","country_code":"US","locality":"Denver"\] | -| url | String | _Nullable_ . A URL provided by the user in association with their profile. Example:

"url": "https://developer.x.com" | -| description | String | _Nullable_ . The user-defined UTF-8 string describing their account. Example:

"description": "The Real X API." | -| protected | Boolean | When true, indicates that this user has chosen to protect their Posts. See [About Public and Protected Posts](https://support.x.com/articles/14016-about-public-and-protected-tweets) . Example:

"protected": true | -| verified | Boolean | When true, indicates that the user has a verified account. See [Verified Accounts](https://support.x.com/articles/119135-faqs-about-verified-accounts) . Example:

"verified": false | -| followers_count | Int | The number of followers this account currently has. Under certain conditions of duress, this field will temporarily indicate “0”. Example:

"followers_count": 21 | -| friends_count | Int | The number of users this account is following (AKA their “followings”). Under certain conditions of duress, this field will temporarily indicate “0”. Example:

"friends_count": 32 | -| listed_count | Int | The number of public lists that this user is a member of. Example:

"listed_count": 9274 | -| favourites_count | Int | The number of Posts this user has liked in the account’s lifetime. British spelling used in the field name for historical reasons. Example:

"favourites_count": 13 | -| statuses_count | Int | The number of Posts (including retweets) issued by the user. Example:

"statuses_count": 42 | -| created_at | String | The UTC datetime that the user account was created on X. Example:

"created_at": "Mon Nov 29 21:18:15 +0000 2010" | -| profile\_banner\_url | String | The HTTPS-based URL pointing to the standard web representation of the user’s uploaded profile banner. By adding a final path element of the URL, it is possible to obtain different image sizes optimized for specific displays. For size variants, please see [User Profile Images and Banners](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/user-profile-images-and-banners) .

Example:

"profile\_banner\_url": "https://si0.twimg.com/profile_banners/819797/1348102824" | -| profile\_image\_url_https | String | A HTTPS-based URL pointing to the user’s profile image. Example:

"profile\_image\_url_https":
"https://abs.twimg.com/sticky/default\_profile\_images/default\_profile\_normal.png" | -| default_profile | Boolean | When true, indicates that the user has not altered the theme or background of their user profile. Example:

"default_profile": false | -| default\_profile\_image | Boolean | When true, indicates that the user has not uploaded their own profile image and a default image is used instead. Example:

"default\_profile\_image": false | - -#### No longer supported (deprecated) attributes - -| Field | Type | Description | -| :--- | :--- | :--- | -| utc_offset | null | Value will be set to null. Still available via [GET account/settings](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-settings) | -| time_zone | null | Value will be set to null. Still available via [GET account/settings](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-settings) as tzinfo_name | -| lang | null | Value will be set to null. Still available via [GET account/settings](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-settings) as language | -| geo_enabled | null | Value will be set to null.  Still available via [GET account/settings](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-settings). This field must be true for the current user to attach geographic data when using [POST statuses / update](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/guides/post-tweet-geo-guide) | -| following | null | Value will be set to null. Still available via [GET friendships/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friendships-lookup) | -| follow\_request\_sent | null | Value will be set to null. Still available via [GET friendships/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friendships-lookup) | -| has\_extended\_profile | null | **Deprecated**. Value will be set to null. | -| notifications | null | **Deprecated**. Value will be set to null. | -| profile_location | null | **Deprecated**. Value will be set to null. | -| contributors_enabled | null | **Deprecated**. Value will be set to null. | -| profile\_image\_url | null | **Deprecated**. Value will be set to null. NOTE: Profile images are only available using the profile\_image\_url_https field. | -| profile\_background\_color | null | **Deprecated**. Value will be set to null. | -| profile\_background\_image_url | null | **Deprecated**. Value will be set to null. | -| profile\_background\_image\_url\_https | null | **Deprecated**. Value will be set to null. | -| profile\_background\_tile | null | **Deprecated**. Value will be set to null. | -| profile\_link\_color | null | **Deprecated**. Value will be set to null. | -| profile\_sidebar\_border_color | null | **Deprecated**. Value will be set to null. | -| profile\_sidebar\_fill_color | null | **Deprecated**. Value will be set to null. | -| profile\_text\_color | null | **Deprecated**. Value will be set to null. | -| profile\_use\_background_image | null | **Deprecated**. Value will be set to null. | -| is_translator | null | **Deprecated**. Value will be set to null. | -| is\_translation\_enabled | null | **Deprecated**. Value will be set to null. | -| translator_type | null | **Deprecated**. Value will be set to null. | - -#### Example user object: - -``` -"user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "X Dev", - "screen_name": "XDevelopers", - "location": "127.0.0.1", - "url": "https://developer.x.com/en/community", - "description": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "translator_type": "regular", - "protected": false, - "verified": true, - "followers_count": 512292, - "friends_count": 2038, - "listed_count": 1666, - "favourites_count": 2147, - "statuses_count": 3634, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "FFFFFF", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_tile": false, - "profile_link_color": "0084B4", - "profile_sidebar_border_color": "FFFFFF", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1594913664", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - } -``` - -### Native Enriched Geo Objects - -Posts can be associated with a location, generating a Post that has been ‘geo-tagged.’ Post locations can be assigned by using the X user-interface or when posting a Post using the API. Post locations can be an exact ‘point’ location, or a X Place with a ‘bounding box’ that describes a larger area ranging from a venue to an entire region. - -There are three ‘root-level’ JSON objects used to describe the location associated with a Post: [place](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#place-data-dictionary), [geo](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-geo-objects) and [coordinates](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#coordinates-object-data-dictionary).  - -Additionally, the native enriched format includes the [profile geo enrichment's](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) [derived location](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#derived-locations) within the user object. - -The `place` object is always present when a Post is geo-tagged with a place,. Places are specific, named locations with corresponding geo coordinates. When users decide to assign a location to their Post, they are presented with a list of candidate X Places. When using the API to post, a X Place can be attached by specifying a place_id when posting. Posts associated with Places are not necessarily issued from that location but could also potentially be _about_ that location. - -The geo and `coordinates` objects only present (non-null) when the Post is assigned an _exact location_. If an exact location is provided, the `coordinates` object will provide a \[long, lat\] array with the geographical coordinates, and a X Place that corresponds to that location will be assigned. - -#### Place data dictionary - - -| Field | Type | Description | -| :--- | :--- | :--- | -| id | String | ID representing this place. Note that this is represented as a string, not an integer. Example:

"id":"01a9a39529b27f36" | -| url | String | URL representing the location of additional place metadata for this place. Example:

"url":"https://api.x.com/1.1/geo/id/01a9a39529b27f36.json" | -| place_type | String | The type of location represented by this place. Example:

"place_type":"city" | -| name | String | Short human-readable representation of the place’s name. Example:

"name":"Manhattan" | -| full_name | String | Full human-readable representation of the place’s name. Example:

"full_name":"Manhattan, NY" | -| country_code | String | Shortened country code representing the country containing this place. Example:

"country_code":"US" | -| country | String | Name of the country containing this place. Example:

"country":"United States" | -| bounding_box | [Object](#obj-boundingbox) | A bounding box of coordinates which encloses this place. Example:


"bounding_box":
"coordinates": \[
\[
\[
-74.026675,
40.683935
\],
\[
-74.026675,
40.877483
\],
\[
-73.910408,
40.877483
\],
\[
-73.910408,
40.3935
\]
\]
\],
"type": "Polygon"

| -| attributes | Object | When using PowerTrack, 30-Day and Full-Archive Search APIs, and Volume Streams this hash is null. Example:

"attributes": {} | - -#### Bounding box[](#bounding-box "Permalink to this headline") - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| coordinates | Array of Array of Array of Float | A series of longitude and latitude points, defining a box which will contain the Place entity this bounding box is related to. Each point is an array in the form of \[longitude, latitude\]. Points are grouped into an array per bounding box. Bounding box arrays are wrapped in one additional array to be compatible with the polygon notation. Example:


"coordinates": \[
\[
\[
-74.026675,
40.683935
\],
\[
-74.026675,
40.877483
\],
\[
-73.910408,
40.877483
\],
\[
-73.910408,
40.3935
\]
\]
\]
| -| type | String | The type of data encoded in the coordinates property. This will be “Polygon” for bounding boxes and “Point” for Posts with exact coordinates. Example:

"type":"Polygon" | - -#### Geo object data dictionary - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| coordinates | Collection of Float | The longitude and latitude of the Post's location, as a collection in the form **\[latitude, longitude\]**. Example:

**  "geo": **

**"type":** "Point"**,**

**    "coordinates": \[**

54.27784**,**

-0.41068

**    \]**

**  ** | -| type | String | The type of data encoded in the coordinates property. This will be “Point” for Post coordinates fields. Example:

"type": "Point" | - -**Coordinates object data dictionary** - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| coordinates | Collection of Float | The longitude and latitude of the Post's location, as a collection in the form **\[longitude, latitude\]**. Example:

**  "coordinates": **

**"type":** "Point"**,**

**    "coordinates": \[**

-0.41068**,**

54.27784

**    \]**

**  ** | -| type | String | The type of data encoded in the coordinates property. This will be “Point” for Post coordinates fields. Example:

"type": "Point" | - -#### Derived locations - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| derived | locations object | Derived location from the profile geo enrichement

**"derived": **

**      "locations": \[**

**        **

**"country":** "United Kingdom"**,**

**"country_code":** "GB"**,**

**"locality":** "Yorkshire"**,**

**"region":** "England"**,**

**"full_name":** "Yorkshire, England, United Kingdom"**,**

**          "geo": **

**            "coordinates": \[**

-1.5**,**

54

**            \],**

**"type":** "point"

**          **

**        **

**      \]**

**    ** | - -#### Examples: -``` -{ - "geo": null, - "coordinates": null, - "place": { - "id": "07d9db48bc083000", - "url": "https://api.x.com/1.1/geo/id/07d9db48bc083000.json", - "place_type": "poi", - "name": "McIntosh Lake", - "full_name": "McIntosh Lake", - "country_code": "US", - "country": "United States", - "bounding_box": { - "type": "Polygon", - "coordinates": [ - [ - [ - -105.14544, - 40.192138 - ], - [ - -105.14544, - 40.192138 - ], - [ - -105.14544, - 40.192138 - ], - [ - -105.14544, - 40.192138 - ] - ] - ] - }, - "attributes": { - - } - } -} -``` -``` -{ - "geo": { - "type": "Point", - "coordinates": [ - 40.74118764, - -73.9998279 - ] - }, - "coordinates": { - "type": "Point", - "coordinates": [ - -73.9998279, - 40.74118764 - ] - }, - "place": { - "id": "01a9a39529b27f36", - "url": "https://api.x.com/1.1/geo/id/01a9a39529b27f36.json", - "place_type": "city", - "name": "Manhattan", - "full_name": "Manhattan, NY", - "country_code": "US", - "country": "United States", - "bounding_box": { - "type": "Polygon", - "coordinates": [ - [ - [ - -74.026675, - 40.683935 - ], - [ - -74.026675, - 40.877483 - ], - [ - -73.910408, - 40.877483 - ], - [ - -73.910408, - 40.683935 - ] - ] - ] - }, - "attributes": { - - } - } -} -``` - - -Data dictionary: Enterprise - -X entities   ------------- - -Jump to on this page - -[Introduction](#intro) - -[Entities object](#entitiesobject) - -  \- [Hashtag object](#hashtags) - -  \- [Media object](#media) - -  \- [Media size object](#media-size) - -  \- [URL object](#urls) - -  \- [User mention object](#mentions) - -  \- [Symbol object](#symbols) - -  \- [Poll object](#polls) - -[Retweet and Quote Tweet details](#retweets-quotes) - -[Entities in user objects](#entities-user) - -[Entities in Direct Messages](#entities-dm) - -[Next Steps](#next) - -Introduction ------------- - -Entities provide metadata and additional contextual information about content posted on X. The `entities` section provides arrays of common things included in Posts: hashtags, user mentions, links, stock tickers (symbols), X polls, and attached media. These arrays are convenient for developers when ingesting Posts, since X has essentially pre-processed, or pre-parsed, the text body. Instead of needing to explicitly search and find these entities in the Post body, your parser can go straight to this JSON section and there they are. - -Beyond providing parsing conveniences, the `entities` section also provides useful ‘value-add’ metadata. For example, if you are using the [Enhanced URLs enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#expanded-and-enhanced-urls), URL metadata include fully-expanded URLs, as well as associated website titles and descriptions. Another example is when there are user mentions, the entities metadata include the numeric user ID, which are useful when making requests to many X APIs. - -Every Post JSON payload includes an `entities` section, with the minimum set of `hashtags`, `urls`, `user_mentions`, and `symbols` attributes, even if none of those entities are part of the Post message. For example, if you examine the JSON for a Post with a body of “Hello World!” and no attached media, the Post's JSON will include the following content with entity arrays containing zero items: - -``` -"entities": { - "hashtags": [ - ], - "urls": [ - ], - "user_mentions": [ - ], - "symbols": [ - ] - } -``` - -Notes: - -* media and polls entities will only appear when that type of content is part of the Post. -* if you are working with native media (photos, videos, or GIFs), the [Extended Entities object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-extended-entities) is the way to go. - -### Entities object - -The `entities` and `extended_entities` sections are both made up of arrays of entity _objects_. Below you will find descriptions for each of these entity objects, including data dictionaries that describe the object attribute names, types, and short description. We’ll also indicate which PowerTrack Operators match these attributes, and include some sample JSON payloads. - -A collection of common entities found in Posts, including hashtags, links, and user mentions. This `entities` object does include a `media` attribute, but its implementation in the `entiites` section is only completely accurate for Posts with a single photo. For all Posts with more than one photo, a video, or animated GIF, the reader is directed to the `extended_entities` section. - -### Entities data dictionary - -The entities object is a holder of arrays of other entity sub-objects. After illustrating the `entities` structure, data dictionaries for these sub-objects, and the Operators that match them, will be provided. - -| Field | Type | Description | -| :--- | :--- | :--- | -| hashtags | Array of [Hashtag Objects](#hashtags) | Represents hashtags which have been parsed out of the Post text. Example:


"hashtags": \[

"indices": \[
32,
38
\],
"text": "nodejs"

\]
| -| media | Array of [Media Objects](#media) | Represents media elements uploaded with the Post. Example:


"media": \[

"display_url": "pic.x.com/5J1WJSRCy9",
"expanded\_url": "https://x.com/nolan\_test/status/930077847535812610/photo/1",
"id": 9.300778475358126e17,
"id_str": "930077847535812610",
"indices": \[
13,
36
\],
"media_url": "http://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg",
"media\_url\_https": "https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg"
"sizes":
       "thumb":
"h": 150,
               "resize": "crop",
               "w": 150
          ,
          "large":
          "h": 1366,
          "resize": "fit",
          "w": 2048
          ,
          "medium":
          "h": 800,
          "resize": "fit",
          "w": 1200
          ,
          "small":
          "h": 454,
          "resize": "fit",
          "w": 680
         
      ,
"type": "photo",
"url": "https://t.co/5J1WJSRCy9",

\]
| -| urls | Array of [URL Objects](#urls) | Represents URLs included in the text of a Post.

Example (without Enhanced URLs enrichment enabled):


"urls": \[

"indices": \[
32,
52
\],
"url": "http://t.co/IOwBrTZR",
"display_url": "youtube.com/watch?v=oHg5SJ…",
"expanded_url": "http://www.youtube.com/watch?v=oHg5SJYRHA0"

\]


Example (with Enhanced URLs enrichment enabled):

"urls": \[

"url": "https://t.co/D0n7a53c2l",
"expanded_url": "http://bit.ly/18gECvy",
"display_url": "bit.ly/18gECvy",
"unwound":
"url": "https://www.youtube.com/watch?v=oHg5SJYRHA0",
"status": 200,
"title": "RickRoll'D",
"description": "http://www.facebook.com/rickroll548 As long as trolls are still trolling, the Rick will never stop rolling."
,
"indices": \[
62,
85
\]

\]
| -| user_mentions | Array of [User Mention Objects](#mentions) | Represents other X users mentioned in the text of the Post. Example:


"user_mentions": \[

"name": "X API",
"indices": \[
4,
15
\],
"screen_name": "xapi",
"id": 6253282,
"id_str": "6253282"

\]
| -| symbols | Array of [Symbol Objects](#symbols) | Represents symbols, i.e. $cashtags, included in the text of the Post. Example:


"symbols": \[

"indices": \[
12,
17
\],
"text": "twtr"

\]
| -| polls | Array of [Poll Objects](#polls) | Represents X Polls included in the Post. Example:

"polls": \[

"options": \[

"position": 1,
"text": "I read documentation once."
,

"position": 2,
"text": "I read documentation twice."
},

"position": 3,
"text": "I read documentation over and over again."
}
\],
"end_datetime": "Thu May 25 22:20:27 +0000 2017",
"duration_minutes": 60

\]
| - -### Hashtag object   - -The `entities` section will contain a `hashtags` array containing an object for every hashtag included in the Post body, and include an empty array if no hashtags are present. - -The PowerTrack `#` Operator is used to match on the `text` attribute. The `has:hashtags` Operator will match if there is at least one item in the array. - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| indices | Array of Int | An array of integers indicating the offsets within the Post text where the hashtag begins and ends. The first integer represents the location of the # character in the Post text string. The second integer represents the location of the first character after the hashtag. Therefore the difference between the two numbers will be the length of the hashtag name plus one (for the ‘#’ character). Example:

"indices":\[32,38\] | -| text | String | Name of the hashtag, minus the leading ‘#’ character. Example:

"text":"nodejs" | - -### Media object   - -The `entities` section will contain a `media` array containing a single media object if any media object has been ‘attached’ to the Post. If no native media has been attached, there will be no `media` array in the `entities`. For the following reasons the `extended_entities` section should be used to process Post native media: -\+ Media `type` will always indicate ‘photo’ even in cases of a video and GIF being attached to Post. -\+ Even though up to four photos can be attached, only the first one will be listed in the `entities` section. - -The `has:media` Operator will match if this array is populated. - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| display_url | String | URL of the media to display to clients. Example:

"display_url":"pic.x.com/rJC5Pxsu" | -| expanded_url | String | An expanded version of display_url. Links to the media display page. Example:

"expanded_url": "http://x.com/yunorno/status/114080493036773378/photo/1" | -| id | Int64 | ID of the media expressed as a 64-bit integer. Example:

"id":114080493040967680 | -| id_str | String | ID of the media expressed as a string. Example:

"id_str":"114080493040967680" | -| indices | Array of Int | An array of integers indicating the offsets within the Post text where the URL begins and ends. The first integer represents the location of the first character of the URL in the Post text. The second integer represents the location of the first non-URL character occurring after the URL (or the end of the string if the URL is the last part of the Post text). Example:

"indices":\[15,35\] | -| media_url | String | An http:// URL pointing directly to the uploaded media file. Example:

"media_url":"http://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg"

For media in direct messages, `media_url` is the same https URL as `media_url_https` and must be accessed by signing a request with the user’s access token using OAuth 1.0A.

It is not possible to access images via an authenticated x.com session. Please visit [this page](https://developer.x.com/en/docs/x-api/v1/direct-messages/message-attachments/guides/retrieving-media) to learn how to account for these recent change. 

You cannot directly embed these images in a web page.

See [Photo Media URL formatting](#photo_format) for how to format a photo's URL, such as `media_url_https`, based on the available `sizes`. | -| media\_url\_https | String | An https:// URL pointing directly to the uploaded media file, for embedding on https pages. Example:

"media\_url\_https":"https://p.twimg.com/AZVLmp-CIAAbkyy.jpg"

For media in direct messages, `media_url_https` must be accessed by signing a request with the user’s access token using OAuth 1.0A.

It is not possible to access images via an authenticated x.com session. Please visit [this page](https://developer.x.com/en/docs/x-api/v1/direct-messages/message-attachments/guides/retrieving-media) to learn how to account for these recent change. 

You cannot directly embed these images in a web page.

See [Photo Media URL formatting](#photo_format) for how to format a photo's URL, such as `media_url_https`, based on the available `sizes`. | -| sizes | [Size Object](#size) | An object showing available sizes for the media file. Example:


"sizes":
"thumb":
"h": 150,
"resize": "crop",
"w": 150
},
"large":
"h": 1366,
"resize": "fit",
"w": 2048
},
"medium":
"h": 800,
"resize": "fit",
"w": 1200
},
"small":
"h": 454,
"resize": "fit",
"w": 680
}
}
}

See [Photo Media URL formatting](#photo_format) for how to format a photo's URL, such as `media_url_https`, based on the available `sizes`. | -| source\_status\_id | Int64 | Nullable. For Posts containing media that was originally associated with a different Post, this ID points to the original Post. Example:

"source\_status\_id": 205282515685081088 | -| source\_status\_id_str | Int64 | Nullable. For Posts containing media that was originally associated with a different post, this string-based ID points to the original Post. Example:

"source\_status\_id_str": "205282515685081088" | -| type | String | Type of uploaded media. Possible types include photo, video, and animated_gif. Example:

"type":"photo" | -| url | String | Wrapped URL for the media link. This corresponds with the URL embedded directly into the raw Post text, and the values for the `indices` parameter. Example:

"url":"http://t.co/rJC5Pxsu" | - -### Media size objects - -All Posts with native media (photos, video, and GIFs) will include a set of ‘thumb’, ‘small’, ‘medium’, and ‘large’ sizes with height and width pixel sizes.  For photos and preview image media URLs, [Photo Media URL formatting](#photo_format) specifies how to construct different URLs for loading different sized photo media. - -#### Sizes object  - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| thumb | [Size Object](#size) | Information for a thumbnail-sized version of the media. Example:

"thumb":"h":150, "resize":"crop", "w":150}

Thumbnail-sized photo media will be limited to _fill_ a 150x150 boundary and cropped. | -| large | [Size Object](#size) | Information for a large-sized version of the media. Example:

"large":"h":454, "resize":"fit", "w":680}

Small-sized photo media will be limited to _fit_ within a 680x680 boundary. | -| medium | [Size Object](#size) | Information for a medium-sized version of the media. Example:

"medium":"h":800, "resize":"fit", "w":1200}

Medium-sized photo media will be limited to _fit_ within a 1200x1200 boundary. | -| small | [Size Object](#size) | Information for a small-sized version of the media. Example:

"small":"h":1366, "resize":"fit", "w":2048}

Large-sized photo media will be limited to _fit_ within a 2048x2048 boundary. | - -#### Size object  - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| w | Int | Width in pixels of this size. Example:

"w":150 | -| h | Int | Height in pixels of this size. Example:

"h":150 | -| resize | String | Resizing method used to obtain this size. A value of _fit_ means that the media was resized to fit one dimension, keeping its native aspect ratio. A value of _crop_ means that the media was cropped in order to fit a specific resolution. Example:

"resize":"crop" | - -### Photo Media URL Formatting - -Photo media on X can be loaded in different sizes.  It is best to load the smallest size image that is larger enough to fit into a particular image viewport.  To load different sizes, the [Size Object](#size) and [media_url](#media) (or [media\_url\_https](#media)) need to be combined in a particular format.  We'll use the [media entity](#entitiesobject) example object already provided for our example in constructing a photo media URL. - -The `media_url` or `media_url_https` on their own can be loaded, which will result in the medium variant being loaded by default.  It is preferable, however, to provide a fully formatted photo media URL when possible. - -There are three parts of a photo media URL: - -| | | -| :--- | :--- | -| Base URL | The base URL is the media URL without the file extension.

For example:

"media\_url\_https": "https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg",

The base URL is then:

_https://pbs.twimg.com/media/DOhM30VVwAEpIHq_ | -| Format | The format is the type of photo the image is formatted as.  Possible formats are _jpg_ or _png_, which is provided as the extension of the media URL.

For example:

"media\_url\_https": "https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg",

The format is then: _jpg_ | -| Name | The name is the field name of the size to load.

For example:


 "sizes":
   "thumb":
     "h": 150,
     "resize": "crop",
     "w": 150
   ,
   "large":
     "h": 1366,
     "resize": "fit",
     "w": 2048
   },
   "medium":
     "h": 800,
     "resize": "fit",
     "w": 1200
   },
   "small":
     "h": 454,
     "resize": "fit",
     "w": 680
   }
 }
}

The name when loading the large-sized photo would be: _large_ | - -We take these three parts (base URL, format and name) and combine them into the photo media URL to load.  There are 2 formats for loading images this way, _legacy_ and _modern_.  All image loads should stop using the _legacy_ format and use the _modern_ format.  Using the _modern_ format will result in better CDN hit rate for the caller, thus improving load latencies by being less likely to have to generate and load the media from the Data Center. - -| | | -| :--- | :--- | -| Legacy format | The legacy format is deprecated.  Photo media loads should all move to the modern format.

_<base_url>.<format>:<name>_

For example:

_https://pbs.twimg.com/media/DOhM30VVwAEpIHq.jpg:large
_ | -| Modern format | The modern format for loading photos was established at X in 2015 and has been defacto since 2017.  All photo media loads should move to this format.

_<base_url>?format=<format>&name=<name>_

For example:

_https://pbs.twimg.com/media/DOhM30VVwAEpIHq?format=jpg&name=large
_

Note: the items in the query string for the photo media URL are in alphabetical order.  If media loading were to add any additional query items, alphabetical ordering would continue to be necessary.  For example, if there was the hypothetical new query item called _preferred_format_, it would go after _format_ and _name_ in the query string. | - -### URL object  - -The `entities` section will contain a `urls` array containing an object for every link included in the Post body, and include an empty array if no links are present. - -The `has:links` Operator will match if there is at least one item in the array. The `url:` Operator is used to match on the `expanded_url` attribute. If you are using the [Expanded URL enrichment](http://support.gnip.com/enrichments/expanded_urls.html), the `url:` Operator is used to match on the `unwound.url` (fully unwound URL) attribute. If you are using the [Exhanced URL enrichment](http://support.gnip.com/enrichments/enhanced_urls.html), the `url_title:` and `url_decription:` Operators are used to match on the `unwound.title` and `unwound.description` attributes. - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| display_url | String | URL pasted/typed into Post. Example:

"display_url":"bit.ly/2so49n2" | -| expanded_url | String | Expanded version of `` display_url`` . Example:

"expanded_url":"http://bit.ly/2so49n2" | -| indices | Array of Int | An array of integers representing offsets within the Post text where the URL begins and ends. The first integer represents the location of the first character of the URL in the Post text. The second integer represents the location of the first non-URL character after the end of the URL. Example:

"indices":\[30,53\] | -| url | String | Wrapped URL, corresponding to the value embedded directly into the raw Post text, and the values for the indices parameter. Example:

"url":"https://t.co/yzocNFvJuL" | - -If you are using the Expanded and/or Enhanced URL enrichments, the following metadata is available under the `unwound` attribute: - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| url | String | The fully unwound version of the link included in the Post. Example:

"url":"https://blog.x.com/en_us/topics/insights/2016/using-twitter-as-a-go-to-communication-channel-during-severe-weather-events.html" | -| status | Int | Final HTTP status of the unwinding process, a '200' indicating success. Example:

200 | -| title | String | HTML title for the link. Example:

"title":"Using X as a ‘go-to’ communication channel during severe weather" | -| description | String | HTML description for the link. Example:

"description":"Using X as a ‘go-to’ communication channel during severe weather" | - -### User mention object   - -The `entities` section will contain a `user_mentions` array containing an object for every user mention included in the Post body, and include an empty array if no user mention is present. - -The PowerTrack `@` Operator is used to match on the `screen_name` attribute. The `has:mentions` Operator will match if there is at least one item in the array. - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| id | Int64 | ID of the mentioned user, as an integer. Example:

"id":6253282 | -| id_str | String | If of the mentioned user, as a string. Example:

"id_str":"6253282" | -| indices | Array of Int | An array of integers representing the offsets within the Post text where the user reference begins and ends. The first integer represents the location of the ‘@’ character of the user mention. The second integer represents the location of the first non-screenname character following the user mention. Example:

"indices":\[4,15\] | -| name | String | Display name of the referenced user. Example:

"name":"API" | -| screen_name | String | Screen name of the referenced user. Example:

"screen_name":"api" | - -### Symbol object   - -The `entities` section will contain a `symbols` array containing an object for every $cashtag included in the Post body, and include an empty array if no symbol is present. - -The PowerTrack `$` Operator is used to match on the `text` attribute. The `has:symbols` Operator will match if there is at least one item in the array. - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| indices | Array of Int | An array of integers indicating the offsets within the Post text where the symbol/cashtag begins and ends. The first integer represents the location of the $ character in the Post text string. The second integer represents the location of the first character after the cashtag. Therefore the difference between the two numbers will be the length of the hashtag name plus one (for the ‘$’ character). Example:

"indices":\[12,17\] | -| text | String | Name of the cashhtag, minus the leading ‘$’ character. Example:

"text":"twtr" | - -### Poll object - -The `entities` section will contain a `polls` array containing a single `poll` object if the Post contains a poll. If no poll is included, there will be no `polls` array in the `entities` section. - -Note that these Poll metadata are only available with the following Enterprise APIs: - -* Volume streams ([Decahose](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api) ) -* [Real-time PowerTrack](/x-api/enterprise-gnip-2.0/powertrack-api) -* X Search APIs ([Full-Archive Search](/x-api/enterprise-gnip-2.0/fundamentals/search-api) and [30-Day Search](/x-api/enterprise-gnip-2.0/fundamentals/search-api)) - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| options | Array of Option Object | An array of options, each having a poll position, and the text for that position. Example:

"options": \[

"position": 1,
"text": "I read documentation once."
}
\]
} | -| end_datetime | String | Time stamp (UTC) of when poll ends. Example:

"end_datetime": "Thu May 25 22:20:27 +0000 2017" | -| duration_minutes | String | Duration of poll in minutes. Example:

"duration_minutes": 60 | - -Retweet and Quote Tweet details -------------------------------- - -From the X API perspective, Retweet and Quote Tweets are special kinds of Posts that contain the original Post as an embedded object. So Retweets and Quote Tweet objects are parents of a child 'original' Post (and thus double the size). Retweets have a top-level "retweeted\_status" object, and Quoted Tweets have a "quoted\_status" object. For consistency, these top-level Retweet and Quote Tweet objects also have a text property and associated entities. However, the entities at the top level can differ from the entities provided by the embedded 'original' entities. In case of Retweets, new text is prepended to the original Post body. For Quoted Posts, new text is appended to the Post body. - -In general, the best practice is to retrieve the text, entities, original author and date from the original Post in retweeted_status whenever this exists. An exception is getting X entities that are part of the additive Quote. See below for more details and tips. - -### Retweets - -An important detail with Retweets is that no additional X _entities_ can be added to the Post. Users can not add hashtags, URLs or other details when they Retweet. However, the Retweet (top-level) text attribute is composed of the original Post text with “RT @username: ” prepended.   - -In some cases, especially with accounts with long user names, the combination of these new characters and the original Post body can easily exceed the original Post text length limit of 140 characters. In order to preserve support for 140 character based display and storage, the top-level body truncates the end of the Post body and adds an ellipsis (“…”). Consequently, some top-level entities positioned at the end of the original Post might be incorrect or missing, for instance in the case of a truncated hashtag or URL entry. - -This Post,  https://x.com/FloodSocial/status/907974220298125312, has the following Post text: - -               Just another test Post that needs to be exactly 140 characters with trailing URL and hashtag ![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet")![](https://abs.twimg.com/emoji/v2/72x72/1f4a7.png "Droplet") [http://wapo.st/2w8iwPQ](https://t.co/R5iMzxWelp "http://wapo.st/2w8iwPQ") [#Testing](https://x.com/hashtag/Testing?src=hash) - -In the above example, both the URL and hashtag were affected. Since the hashtag was completely truncated and the URL partially truncated, these are missing from the the top-level entities. You will also notice the additional user_mentions top-level entity coming from the “RT @floodsocial: ” prefix on the text field. - -However, the Post text and entities in retweeted_status perfectly reflect the original Post with no truncation or incorrect entities, hence our recommendation to rely on the nested _retweeted_status _object for Retweets. - -### Quote Tweets - -Quote Tweets were introduced in 2016, and differ from Retweets in that when you "quote" a Pos you are adding new content "on top" of a shared Post. This new content can include nearly anything an original Post can have, including new text, hashtags, mentions, and URLs. - -Quote Tweets can contain native media (photos, videos, and GIFs), and will appear under the entities object. - -Since X entities can be added, the Quote entities are likely different from the original entities. - -In this example, a new URL and hashtag were positioned at the end of the Quote Tweet. - -This Post, https://x.com/FloodSocial/status/907983973225160704, has the following Post text: - -                  strange and equally tragic when islands flood... trans-atlantic testing of quote tweets | [@thisuser](https://x.com/andypiper) [@thatuser](https://x.com/johnd)[http://bit.ly/2vMMDuu](https://t.co/fzFgMhWlPO "http://bit.ly/2vMMDuu") [#testing](https://x.com/hashtag/testing?src=hash) - -In this case, the top-level entities do not reflect the Quote details.  - -However, the Post text and entities in extended_tweet perfectly reflect the Quote Tweet with no truncation or incorrect entities, hence our recommendation to rely on the nested _extended_tweet _object for Quote Tweets. - -### Entities for user object - -Entities for User Objects describe URLs that appear in the user defined profile URL and description fields. They do not describe hashtags or user_mentions. Unlike Post entities, user entities can apply to multiple fields within its parent object — to disambiguate, you will find a parent nodes called url and description that indicate which field contains the entitized URL. - -In this example, the user url field contains a t.co link that is fully expanded within the entities/url/urls\[0\] node of the response. The user does not have a wrapped URL in their description. - -#### JSON example - -``` -{ - "id": 6253282, - "id_str": "6253282", - "name": "X API", - "screen_name": "xapi", - "location": "San Francisco, CA", - "description": "The Real X API. I tweet about API changes, service issues and happily answer questions about X and our API. Don't get an answer? It's on my website.", - "url": "http:\/\/t.co\/78pYTvWfJd", - "entities": { - "url": { - "urls": [ - { - "url": "http:\/\/t.co\/78pYTvWfJd", - "expanded_url": "http:\/\/dev.x.com", - "display_url": "dev.x.com", - "indices": [ - 0, - 22 - ] - } - ] - }, - "description": { - "urls": [ - - ] - } - } -} -``` - -### X extended entities  - - -Jump to on this page - -[Introduction](#intro) - -[Extended Entities object](#extended-entities-object) - -[Example Tweets and JSON payloads](#example-json) - -  \- [Tweet with four native photos](#tweet-photos) - -  \- [Tweet with native video](#tweet-video) - -  \- [Tweet with an animated GIF](#tweet-gif) - -[Next Steps](#next) - -#### Introduction - -If a Post contains native media (shared with the Post user-interface as opposed via a link to elsewhere), there will also be a extended\_entities section. When it comes to any native media (photo, video, or GIF), the extended\_entities is the preferred metadata source for several reasons. Currently, up to four photos can be attached to a Post. The entities metadata will only contain the first photo (until 2014, only one photo could be included), while the extended\_entities section will include all attached photos. With native media, another deficiency of the entities.media metadata is that the media type will always indicate ‘photo’, even in cases where the attached media is a video or animated GIF. The actual type of media is specified in the extended\_entities.media\[\].type attribute and is set to either _photo_, _video_, or _animated_gif_. For these reasons, if you are working with native media, the extended_entities metadata is the way to go. - -All Posts with attached photos, videos and animated GIFs will include an `extended_entities` JSON object. The `extended_entities` object contains a single `media` array of `media` objects (see the `entities` section for its data dictionary). No other entity types, such as hashtags and links, are included in the `extended_entities` section. The `media` object in the `extended_entities` section is identical in structure to the one included in the `entities` section. - -Posts can only have one type of media attached to it. For photos, up to four photos can be attached. For videos and GIFs, one can be attached. Since the media `type` metadata in the `extended_entities` section correctly indicates the media type (‘photo’, ‘video’ or ‘animated_gif’), and supports up to 4 photos, it is the preferred metadata source for native media. -``` -{ - "extended_entities": { - "media": [ - - ] - } - } -``` - -#### Example Posts and JSON payloads - -Below are some example Posts and their associated entities metadata. - -Post with four native photos - -Post with hashtag, user mention, cashtag, URL, and four native photos: - - -Here is the `entities` section for this Post: - -``` -{ - "entities": { - "hashtags": [ - { - "text": "hashtag", - "indices": [ - 59, - 67 - ] - } - ], - "urls": [ - { - "url": "https://t.co/RzmrQ6wAzD", - "expanded_url": "http://bit.ly/2pUk4be", - "display_url": "bit.ly/2pUk4be", - "unwound": { - "url": "https://blog.gnip.com/tweeting-in-the-rain/", - "status": 200, - "title": "Tweeting in the Rain, Part 1 - Gnip Blog - Social Data and Data Science Blog", - "description": "If you would have told me a few years ago that one day I’d be comparing precipitation and social media time-series data, I would have assumed you were joking. For 13 years at OneRain I helped develop software and monitoring … Continue reading →" - }, - "indices": [ - 35, - 58 - ] - } - ], - "user_mentions": [ - { - "screen_name": "MentionThis", - "name": "Just Me", - "id": 50247739, - "id_str": "50247739", - "indices": [ - 16, - 28 - ] - } - ], - "symbols": [ - { - "text": "twtr", - "indices": [ - 29, - 34 - ] - } - ], - "media": [ - { - "id": 861627472244162561, - "id_str": "861627472244162561", - "indices": [ - 68, - 91 - ], - "media_url": "http://pbs.twimg.com/media/C_UdnvPUwAE3Dnn.jpg", - "media_url_https": "https://pbs.twimg.com/media/C_UdnvPUwAE3Dnn.jpg", - "url": "https://t.co/9r69akA484", - "display_url": "pic.x.com/9r69akA484", - "expanded_url": "https://x.com/FloodSocial/status/861627479294746624/photo/1", - "type": "photo", - "sizes": { - "medium": { - "w": 1200, - "h": 900, - "resize": "fit" - }, - "small": { - "w": 680, - "h": 510, - "resize": "fit" - }, - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "large": { - "w": 2048, - "h": 1536, - "resize": "fit" - } - } - } - ] - } - } -``` -Only in this ‘extended’ payload below will you find the four (maximum) native photos. Notice that the first photo in the array is the same as the single photo included in the non-extended X _entities_ section. The _media_ metadata structure for photos is the same for both _entities_ and _extended_entities_ sections. - -Here is the `extented_entities` section for this Post: - -``` -{ - "extended_entities": { - "media": [ - { - "id": 861627472244162561, - "id_str": "861627472244162561", - "indices": [ - 68, - 91 - ], - "media_url": "http://pbs.twimg.com/media/C_UdnvPUwAE3Dnn.jpg", - "media_url_https": "https://pbs.twimg.com/media/C_UdnvPUwAE3Dnn.jpg", - "url": "https://t.co/9r69akA484", - "display_url": "pic.x.com/9r69akA484", - "expanded_url": "https://x.com/FloodSocial/status/861627479294746624/photo/1", - "type": "photo", - "sizes": { - "medium": { - "w": 1200, - "h": 900, - "resize": "fit" - }, - "small": { - "w": 680, - "h": 510, - "resize": "fit" - }, - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "large": { - "w": 2048, - "h": 1536, - "resize": "fit" - } - } - }, - { - "id": 861627472244203520, - "id_str": "861627472244203520", - "indices": [ - 68, - 91 - ], - "media_url": "http://pbs.twimg.com/media/C_UdnvPVYAAZbEs.jpg", - "media_url_https": "https://pbs.twimg.com/media/C_UdnvPVYAAZbEs.jpg", - "url": "https://t.co/9r69akA484", - "display_url": "pic.x.com/9r69akA484", - "expanded_url": "https://x.com/FloodSocial/status/861627479294746624/photo/1", - "type": "photo", - "sizes": { - "small": { - "w": 680, - "h": 680, - "resize": "fit" - }, - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "medium": { - "w": 1200, - "h": 1200, - "resize": "fit" - }, - "large": { - "w": 2048, - "h": 2048, - "resize": "fit" - } - } - }, - { - "id": 861627474144149504, - "id_str": "861627474144149504", - "indices": [ - 68, - 91 - ], - "media_url": "http://pbs.twimg.com/media/C_Udn2UUQAADZIS.jpg", - "media_url_https": "https://pbs.twimg.com/media/C_Udn2UUQAADZIS.jpg", - "url": "https://t.co/9r69akA484", - "display_url": "pic.x.com/9r69akA484", - "expanded_url": "https://x.com/FloodSocial/status/861627479294746624/photo/1", - "type": "photo", - "sizes": { - "medium": { - "w": 1200, - "h": 900, - "resize": "fit" - }, - "small": { - "w": 680, - "h": 510, - "resize": "fit" - }, - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "large": { - "w": 2048, - "h": 1536, - "resize": "fit" - } - } - }, - { - "id": 861627474760708096, - "id_str": "861627474760708096", - "indices": [ - 68, - 91 - ], - "media_url": "http://pbs.twimg.com/media/C_Udn4nUMAAgcIa.jpg", - "media_url_https": "https://pbs.twimg.com/media/C_Udn4nUMAAgcIa.jpg", - "url": "https://t.co/9r69akA484", - "display_url": "pic.x.com/9r69akA484", - "expanded_url": "https://x.com/FloodSocial/status/861627479294746624/photo/1", - "type": "photo", - "sizes": { - "small": { - "w": 680, - "h": 680, - "resize": "fit" - }, - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "medium": { - "w": 1200, - "h": 1200, - "resize": "fit" - }, - "large": { - "w": 2048, - "h": 2048, - "resize": "fit" - } - } - } - ] - } - } -``` -#### Post with native video - -Below is the extended entities metadata for this Post with a video: - - -```json -{ - "extended_entities": { - "media": [ - { - "id": 869317980307415040, - "id_str": "869317980307415040", - "indices": [ - 31, - 54 - ], - "media_url": "http://pbs.twimg.com/ext_tw_video_thumb/869317980307415040/pu/img/t_E6wyADk_PvxuzF.jpg", - "media_url_https": "https://pbs.twimg.com/ext_tw_video_thumb/869317980307415040/pu/img/t_E6wyADk_PvxuzF.jpg", - "url": "https://t.co/TLSTTOvvmP", - "display_url": "pic.x.com/TLSTTOvvmP", - "expanded_url": "https://x.com/FloodSocial/status/869318041078820864/video/1", - "type": "video", - "sizes": { - "small": { - "w": 340, - "h": 604, - "resize": "fit" - }, - "large": { - "w": 720, - "h": 1280, - "resize": "fit" - }, - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "medium": { - "w": 600, - "h": 1067, - "resize": "fit" - } - }, - "video_info": { - "aspect_ratio": [ - 9, - 16 - ], - "duration_millis": 10704, - "variants": [ - { - "bitrate": 320000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/869317980307415040/pu/vid/180x320/FMei8yCw7yc_Z7e-.mp4" - }, - { - "bitrate": 2176000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/869317980307415040/pu/vid/720x1280/octt5pFbISkef8RB.mp4" - }, - { - "bitrate": 832000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/869317980307415040/pu/vid/360x640/2OmqK74SQ9jNX8mZ.mp4" - }, - { - "content_type": "application/x-mpegURL", - "url": "https://video.twimg.com/ext_tw_video/869317980307415040/pu/pl/wcJQJ2nxiFU4ZZng.m3u8" - } - ] - } - } - ] - } - } -``` - -When an advertiser chooses to limit video playback to just X owned and operated platforms, the `video_info` object will be replaced with an `additional_media_info` object. - -The `additional_media_info` will contain additional media info provided by the publisher, such as `title`, `description` and `embeddable flag`. Video content is made available only to X official clients when `embeddable=false`. In this case, all video URLs provided in the payload will be X-based, so the user can open the video in a X owned property by clicking the link. - -Here is an example of what the extended entities object will look like in this situation: -```json -{ - "extended_entities": { - "media": [ - { - "id": 924685332347469824, - "id_str": "924685332347469824", - "indices": [ - 49, - 72 - ], - "media_url": "http://pbs.twimg.com/media/DNUkdLMVwAEzj8K.jpg", - "media_url_https": "https://pbs.twimg.com/media/DNUkdLMVwAEzj8K.jpg", - "url": "https://t.co/90xOJqKMox", - "display_url": "pic.x.com/90xOJqKMox", - "expanded_url": "https://x.com/nyjets/status/924685391524798464/video/1", - "type": "photo", - "sizes": { - "small": { - "w": 680, - "h": 383, - "resize": "fit" - }, - "medium": { - "w": 1200, - "h": 675, - "resize": "fit" - }, - "large": { - "w": 1280, - "h": 720, - "resize": "fit" - }, - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - } - }, - "additional_media_info": { - "title": "#ATLvsNYJ: Tomlinson TD from McCown", - "description": "NFL", - "embeddable": false, - "monetizable": true - } - } - ] - } - } -``` -As discussed above, here is the `entities` section that incorrectly has the `type` set to ‘photo’. Again, the `extended_entities` section is preferred for all native media types, including ‘video’ and ‘animated_gif’. -```json - { - "entities": { - "hashtags": [ - - ], - "urls": [ - - ], - "user_mentions": [ - - ], - "symbols": [ - - ], - "media": [ - { - "id": 869317980307415040, - "id_str": "869317980307415040", - "indices": [ - 31, - 54 - ], - "media_url": "http://pbs.twimg.com/ext_tw_video_thumb/869317980307415040/pu/img/t_E6wyADk_PvxuzF.jpg", - "media_url_https": "https://pbs.twimg.com/ext_tw_video_thumb/869317980307415040/pu/img/t_E6wyADk_PvxuzF.jpg", - "url": "https://t.co/TLSTTOvvmP", - "display_url": "pic.x.com/TLSTTOvvmP", - "expanded_url": "https://x.com/FloodSocial/status/869318041078820864/video/1", - "type": "photo", - "sizes": { - "small": { - "w": 340, - "h": 604, - "resize": "fit" - }, - "large": { - "w": 720, - "h": 1280, - "resize": "fit" - }, - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "medium": { - "w": 600, - "h": 1067, - "resize": "fit" - } - } - } - ] - } - - } - ``` - -#### Post with an animated GIF - -Below is the extended entities metadata for this Post with an animated GIF: -```json -{ - "extended_entities": { - "media": [ - { - "id": 870042654213459968, - "id_str": "870042654213459968", - "indices": [ - 29, - 52 - ], - "media_url": "http://pbs.twimg.com/tweet_video_thumb/DBMDLy_U0AAqUWP.jpg", - "media_url_https": "https://pbs.twimg.com/tweet_video_thumb/DBMDLy_U0AAqUWP.jpg", - "url": "https://t.co/nD6G4bWSKb", - "display_url": "pic.x.com/nD6G4bWSKb", - "expanded_url": "https://x.com/FloodSocial/status/870042717589340160/photo/1", - "type": "animated_gif", - "sizes": { - "medium": { - "w": 350, - "h": 262, - "resize": "fit" - }, - "small": { - "w": 340, - "h": 255, - "resize": "fit" - }, - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "large": { - "w": 350, - "h": 262, - "resize": "fit" - } - }, - "video_info": { - "aspect_ratio": [ - 175, - 131 - ], - "variants": [ - { - "bitrate": 0, - "content_type": "video/mp4", - "url": "https://video.twimg.com/tweet_video/DBMDLy_U0AAqUWP.mp4" - } - ] - } - } - ] - } - } -``` - -### Native Enriched example payloads -#### Post - -``` -{ - "created_at": "Fri Sep 18 18:36:15 +0000 2020", - "id": 1307025659294675000, - "id_str": "1307025659294674945", - "text": "Here’s an article that highlights the updates in the new Tweet payload v2 https://t.co/oeF3ZHeKQQ", - "source": "X Web App", - "truncated": false, - "in_reply_to_status_id": 1304102743196356600, - "in_reply_to_status_id_str": "1304102743196356610", - "in_reply_to_user_id": 2244994945, - "in_reply_to_user_id_str": "2244994945", - "in_reply_to_screen_name": "XDevelopers", - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "X Dev", - "screen_name": "XDevelopers", - "location": "127.0.0.1", - "url": "https://developer.x.com/en/community", - "description": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "translator_type": "regular", - "protected": false, - "verified": true, - "followers_count": 512292, - "friends_count": 2038, - "listed_count": 1666, - "favourites_count": 2147, - "statuses_count": 3634, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "FFFFFF", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_tile": false, - "profile_link_color": "0084B4", - "profile_sidebar_border_color": "FFFFFF", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1594913664", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "quote_count": 1, - "reply_count": 2, - "retweet_count": 11, - "favorite_count": 70, - "entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/oeF3ZHeKQQ", - "expanded_url": "https://dev.to/twitterdev/understanding-the-new-tweet-payload-in-the-twitter-api-v2-1fg5", - "display_url": "dev.to/twitterdev/und…", - "unwound": { - "url": "https://dev.to/twitterdev/understanding-the-new-tweet-payload-in-the-twitter-api-v2-1fg5", - "status": 200, - "title": "Understanding the new Tweet payload in the X API v2", - "description": "X recently announced the new X API v2, rebuilt from the ground up to deliver new features..." - }, - "indices": [ - 74, - 97 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [{ - "tag": null - }] -} -``` - -#### Post reply - -``` -{ - "created_at": "Fri Aug 21 19:10:05 +0000 2020", - "id": 1296887316556980200, - "id_str": "1296887316556980230", - "text": "See how @PennMedCDH are using X data to understand the COVID-19 health crisis 📊\n\nhttps://t.co/1tdA8uDWes", - "source": "X Web App", - "truncated": false, - "in_reply_to_status_id": 1296887091901718500, - "in_reply_to_status_id_str": "1296887091901718529", - "in_reply_to_user_id": 2244994945, - "in_reply_to_user_id_str": "2244994945", - "in_reply_to_screen_name": "XDevelopers", - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "X Dev", - "screen_name": "XDevelopers", - "location": "127.0.0.1", - "url": "https://developer.x.com/en/community", - "description": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "translator_type": "regular", - "protected": false, - "verified": true, - "followers_count": 512292, - "friends_count": 2038, - "listed_count": 1666, - "favourites_count": 2147, - "statuses_count": 3634, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "FFFFFF", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_tile": false, - "profile_link_color": "0084B4", - "profile_sidebar_border_color": "FFFFFF", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1594913664", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "quote_count": 2, - "reply_count": 3, - "retweet_count": 9, - "favorite_count": 26, - "entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/1tdA8uDWes", - "expanded_url": "https://developer.x.com/en/use-cases/success-stories/penn", - "display_url": "developer.x.com/en/use-cases/s…", - "unwound": { - "url": "https://developer.x.com/en/use-cases/success-stories/penn", - "status": 200, - "title": "Penn Medicine Center for Digital Health", - "description": "Penn Med Center for Digital Health has created a COVID-19 X map that includes charts detailing sentiment, symptoms reported, state-by-state data cuts, and border data on the COVID-19 outbreak. In addition, their Penn Med With You initiative uses aggregate regional information from X to inform their website and text-messaging service. The service uses this information to disseminate relevant and timely resources." - }, - "indices": [ - 87, - 110 - ] - }], - "user_mentions": [{ - "screen_name": "PennMedCDH", - "name": "Penn Med CDH", - "id": 1615654896, - "id_str": "1615654896", - "indices": [ - 8, - 19 - ] - }], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [{ - "tag": null - }] -} -``` - -#### Extended Post - -``` -{ - "created_at": "Wed Aug 19 16:26:16 +0000 2020", - "id": 1296121314218897400, - "id_str": "1296121314218897408", - "text": "The hide replies endpoint is launching today! \n\nDevelopers can hide replies to Tweets - a crucial way developers ca… https://t.co/VyfXs1RTXn", - "source": "X Web App", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "X Dev", - "screen_name": "XDevelopers", - "location": "127.0.0.1", - "url": "https://developer.x.com/en/community", - "description": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "translator_type": "regular", - "protected": false, - "verified": true, - "followers_count": 512292, - "friends_count": 2038, - "listed_count": 1666, - "favourites_count": 2147, - "statuses_count": 3634, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "FFFFFF", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_tile": false, - "profile_link_color": "0084B4", - "profile_sidebar_border_color": "FFFFFF", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1594913664", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "The hide replies endpoint is launching today! \n\nDevelopers can hide replies to Tweets - a crucial way developers can help improve the health of the public conversation using the #XAPI.\n\nhttps://t.co/khXhTurm9x", - "display_text_range": [ - 0, - 215 - ], - "entities": { - "hashtags": [{ - "text": "XAPI", - "indices": [ - 178, - 189 - ] - }], - "urls": [{ - "url": "https://t.co/khXhTurm9x", - "expanded_url": "https://devcommunity.x.com/t/hide-replies-now-available-in-the-new-twitter-api/140996", - "display_url": "devcommunity.com/t/hide-replies…", - "unwound": { - "url": "https://devcommunity.x.com/t/hide-replies-now-available-in-the-new-twitter-api/140996", - "status": 200, - "title": "Hide replies now available in the new X API", - "description": "Today, we’re happy to announce the general availability of the hide replies endpoint in the new X API. The hide replies endpoint allows you to build tools that help people hide or unhide replies to their Tweets. People manage their replies for many reasons, including to give less attention to comments that are abusive, distracting, misleading, or to make conversations more engaging. Through this endpoint, you can build tools to help people on X hide or unhide replies faster and more..." - }, - "indices": [ - 192, - 215 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "quote_count": 23, - "reply_count": 9, - "retweet_count": 54, - "favorite_count": 172, - "entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/VyfXs1RTXn", - "expanded_url": "https://x.com/i/web/status/1296121314218897408", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [{ - "tag": null - }] -} -``` - -#### Post with extended_entitites - -``` -{ - "created_at": "Wed Aug 12 17:01:42 +0000 2020", - "id": 1293593516040269800, - "id_str": "1293593516040269825", - "text": "It’s finally here! 🥁 Say hello to the new #XAPI.\n\nWe’re rebuilding the X API v2 from the ground up to b… https://t.co/UeCndQGMjx", - "display_text_range": [ - 0, - 140 - ], - "source": "X Web App", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "X Dev", - "screen_name": "XDevelopers", - "location": "127.0.0.1", - "url": "https://developer.x.com/en/community", - "description": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "translator_type": "regular", - "protected": false, - "verified": true, - "followers_count": 512292, - "friends_count": 2038, - "listed_count": 1666, - "favourites_count": 2147, - "statuses_count": 3634, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "FFFFFF", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_tile": false, - "profile_link_color": "0084B4", - "profile_sidebar_border_color": "FFFFFF", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1594913664", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "It’s finally here! 🥁 Say hello to the new #XAPI.\n\nWe’re rebuilding the X API v2 from the ground up to better serve our developer community. And today’s launch is only the beginning.\n\nhttps://t.co/32VrwpGaJw https://t.co/KaFSbjWUA8", - "display_text_range": [ - 0, - 218 - ], - "entities": { - "hashtags": [{ - "text": "XAPI", - "indices": [ - 42, - 53 - ] - }], - "urls": [{ - "url": "https://t.co/32VrwpGaJw", - "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/introducing_new_twitter_api.html", - "display_url": "blog.x.com/developer/en_u…", - "unwound": { - "url": "https://blog.x.com/developer/en_us/topics/tools/2020/introducing_new_twitter_api.html", - "status": 200, - "title": "Introducing a new and improved X API", - "description": "Introducing the new X API - rebuilt from the ground up to deliver new features faster so developers can help the world connect to the public conversation happening on X." - }, - "indices": [ - 195, - 218 - ] - }], - "user_mentions": [], - "symbols": [], - "media": [{ - "id": 1293565706408038400, - "id_str": "1293565706408038401", - "indices": [ - 219, - 242 - ], - "additional_media_info": { - "monetizable": false - }, - "media_url": "http://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "media_url_https": "https://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "url": "https://t.co/KaFSbjWUA8", - "display_url": "pic.x.com/KaFSbjWUA8", - "expanded_url": "https://x.com/XDevelopers/status/1293593516040269825/video/1", - "type": "video", - "video_info": { - "aspect_ratio": [ - 16, - 9 - ], - "duration_millis": 34875, - "variants": [{ - "bitrate": 256000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/480x270/Fg9lnGGsITO0uq2K.mp4?tag=10" - }, - { - "bitrate": 832000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/640x360/-crbtZE4y8vKN_uF.mp4?tag=10" - }, - { - "content_type": "application/x-mpegURL", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/pl/OvIqQojosF6sMIHR.m3u8?tag=10" - }, - { - "bitrate": 2176000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/1280x720/xkxyb-VPVY4OI0j9.mp4?tag=10" - } - ] - }, - "sizes": { - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "medium": { - "w": 1200, - "h": 675, - "resize": "fit" - }, - "small": { - "w": 680, - "h": 383, - "resize": "fit" - }, - "large": { - "w": 1280, - "h": 720, - "resize": "fit" - } - } - }] - }, - "extended_entities": { - "media": [{ - "id": 1293565706408038400, - "id_str": "1293565706408038401", - "indices": [ - 219, - 242 - ], - "additional_media_info": { - "monetizable": false - }, - "media_url": "http://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "media_url_https": "https://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "url": "https://t.co/KaFSbjWUA8", - "display_url": "pic.x.com/KaFSbjWUA8", - "expanded_url": "https://x.com/XDevelopers/status/1293593516040269825/video/1", - "type": "video", - "video_info": { - "aspect_ratio": [ - 16, - 9 - ], - "duration_millis": 34875, - "variants": [{ - "bitrate": 256000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/480x270/Fg9lnGGsITO0uq2K.mp4?tag=10" - }, - { - "bitrate": 832000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/640x360/-crbtZE4y8vKN_uF.mp4?tag=10" - }, - { - "content_type": "application/x-mpegURL", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/pl/OvIqQojosF6sMIHR.m3u8?tag=10" - }, - { - "bitrate": 2176000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/1280x720/xkxyb-VPVY4OI0j9.mp4?tag=10" - } - ] - }, - "sizes": { - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "medium": { - "w": 1200, - "h": 675, - "resize": "fit" - }, - "small": { - "w": 680, - "h": 383, - "resize": "fit" - }, - "large": { - "w": 1280, - "h": 720, - "resize": "fit" - } - } - }] - } - }, - "quote_count": 332, - "reply_count": 172, - "retweet_count": 958, - "favorite_count": 2844, - "entities": { - "hashtags": [{ - "text": "XAPI", - "indices": [ - 42, - 53 - ] - }], - "urls": [{ - "url": "https://t.co/UeCndQGMjx", - "expanded_url": "https://x.com/i/web/status/1293593516040269825", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [{ - "tag": null - }] -} -``` - -#### Retweet - -``` -{ - "created_at": "Tue Feb 18 19:33:59 +0000 2020", - "id": 1229851574555508700, - "id_str": "1229851574555508737", - "text": "RT @suhemparack: I built an Alexa Skill for X using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it out her…", - "source": "X Web App", - "truncated": false, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "X Dev", - "screen_name": "X Developers", - "location": "127.0.0.1", - "url": "https://developer.x.com/en/community", - "description": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "translator_type": "regular", - "protected": false, - "verified": true, - "followers_count": 512292, - "friends_count": 2038, - "listed_count": 1666, - "favourites_count": 2147, - "statuses_count": 3634, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "FFFFFF", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_tile": false, - "profile_link_color": "0084B4", - "profile_sidebar_border_color": "FFFFFF", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1594913664", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "retweeted_status": { - "created_at": "Tue Feb 18 19:01:58 +0000 2020", - "id": 1229843515603144700, - "id_str": "1229843515603144704", - "text": "I built an Alexa Skill for X using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it… https://t.co/RP9NgltX7i", - "source": "X Web App", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 857699969263964200, - "id_str": "857699969263964161", - "name": "Suhem Parack", - "screen_name": "suhemparack", - "location": "Seattle, WA", - "url": "https://developer.x.com", - "description": "Developer Relations for Academic Research @X. Talk to me about research with X data. Previously: Amazon Alexa. Views are my own", - "translator_type": "none", - "protected": false, - "verified": false, - "followers_count": 732, - "friends_count": 501, - "listed_count": 12, - "favourites_count": 358, - "statuses_count": 458, - "created_at": "Thu Apr 27 20:56:22 +0000 2017", - "utc_offset": null, - "time_zone": null, - "geo_enabled": false, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "F5F8FA", - "profile_background_image_url": "", - "profile_background_image_url_https": "", - "profile_background_tile": false, - "profile_link_color": "1DA1F2", - "profile_sidebar_border_color": "C0DEED", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": true, - "profile_image_url": "http://pbs.twimg.com/profile_images/1230703695051935747/TbQKe91L_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1230703695051935747/TbQKe91L_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/857699969263964161/1593055939", - "default_profile": true, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "I built an Alexa Skill for X using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it out here 👇\n\nhttps://t.co/l5J8wq748G", - "display_text_range": [ - 0, - 150 - ], - "entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/l5J8wq748G", - "expanded_url": "https://dev.to/twitterdev/building-an-alexa-skill-for-twitter-using-alexa-presentation-language-1aj0", - "display_url": "dev.to/twitterdev/bui…", - "unwound": { - "url": "https://dev.to/twitterdev/building-an-alexa-skill-for-twitter-using-alexa-presentation-language-1aj0", - "status": 200, - "title": null, - "description": null - }, - "indices": [ - 127, - 150 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "quote_count": 6, - "reply_count": 1, - "retweet_count": 19, - "favorite_count": 71, - "entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/RP9NgltX7i", - "expanded_url": "https://x.com/i/web/status/1229843515603144704", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 116, - 139 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en" - }, - "is_quote_status": false, - "quote_count": 0, - "reply_count": 0, - "retweet_count": 0, - "favorite_count": 0, - "entities": { - "hashtags": [], - "urls": [], - "user_mentions": [{ - "screen_name": "suhemparack", - "name": "Suhem Parack", - "id": 857699969263964200, - "id_str": "857699969263964161", - "indices": [ - 3, - 15 - ] - }], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [{ - "tag": null - }] -} -``` - -#### Quote Tweet - -``` -{ - "created_at": "Mon Nov 16 18:09:36 +0000 2020", - "id": 1328399838128468000, - "id_str": "1328399838128467969", - "text": "As planned, the Labs v2 endpoints referenced below have now been retired. Please let us know in the forums if you h… https://t.co/ahQvTYaOcZ", - "display_text_range": [ - 0, - 140 - ], - "source": "X Web App", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "X Dev", - "screen_name": "XDevelopers", - "location": "127.0.0.1", - "url": "https://developer.x.com/en/community", - "description": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "translator_type": "regular", - "protected": false, - "verified": true, - "followers_count": 512292, - "friends_count": 2038, - "listed_count": 1666, - "favourites_count": 2147, - "statuses_count": 3634, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "FFFFFF", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_tile": false, - "profile_link_color": "0084B4", - "profile_sidebar_border_color": "FFFFFF", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1594913664", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "quoted_status_id": 1327011423252144000, - "quoted_status_id_str": "1327011423252144128", - "quoted_status": { - "created_at": "Thu Nov 12 22:12:32 +0000 2020", - "id": 1327011423252144000, - "id_str": "1327011423252144128", - "text": "👋 Friendly reminder that X Developer Labs v2 hide replies and recent search will be retired next Monday, Nove… https://t.co/EEWN2Q9aXh", - "source": "X Web App", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "X Dev", - "screen_name": "XDevelopers", - "location": "127.0.0.1", - "url": "https://developer.x.com/en/community", - "description": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "translator_type": "regular", - "protected": false, - "verified": true, - "followers_count": 512292, - "friends_count": 2038, - "listed_count": 1666, - "favourites_count": 2147, - "statuses_count": 3634, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "FFFFFF", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_tile": false, - "profile_link_color": "0084B4", - "profile_sidebar_border_color": "FFFFFF", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1594913664", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "👋 Friendly reminder that X Developer Labs v2 hide replies and recent search will be retired next Monday, November 16! We encourage you to migrate to the new hide replies and recent search endpoints now available in the v2 #XAPI. Details: https://t.co/r6z6CI7kEy", - "display_text_range": [ - 0, - 273 - ], - "entities": { - "hashtags": [{ - "text": "XAPI", - "indices": [ - 228, - 239 - ] - }], - "urls": [{ - "url": "https://t.co/r6z6CI7kEy", - "expanded_url": "https://devcommunity.x.com/t/retiring-labs-v2-recent-search-and-hide-replies/145795", - "display_url": "devcommunity.com/t/retiring-lab…", - "unwound": { - "url": "https://devcommunity.x.com/t/retiring-labs-v2-recent-search-and-hide-replies/145795", - "status": 200, - "title": "Retiring Labs v2 recent search and hide replies", - "description": "As we said in our Early Access and hide replies announcements, the following X Developer Labs v2 endpoints will be retired on November 16th. Labs v2 recent search Labs v2 hide replies If called, these endpoints will respond with an HTTP 410 status and return no data. Based on your feedback from Labs, we incorporated corresponding functionality into the X API v2. The relevant documentation can be found using the links below. Click here to enroll in v2 access if you haven’t already..." - }, - "indices": [ - 250, - 273 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "quote_count": 4, - "reply_count": 2, - "retweet_count": 8, - "favorite_count": 33, - "entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/EEWN2Q9aXh", - "expanded_url": "https://x.com/i/web/status/1327011423252144128", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en" - }, - "quoted_status_permalink": { - "url": "https://t.co/JaxttUMmjX", - "expanded": "https://x.com/XDevelopers/status/1327011423252144128", - "display": "x.com/XDevelopers/sta…" - }, - "is_quote_status": true, - "extended_tweet": { - "full_text": "As planned, the Labs v2 endpoints referenced below have now been retired. Please let us know in the forums if you have questions or need help with the X API v2! https://t.co/JaxttUMmjX", - "display_text_range": [ - 0, - 166 - ], - "entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/JaxttUMmjX", - "expanded_url": "https://x.com/XDevelopers/status/1327011423252144128", - "display_url": "x.com/XDevelopers/sta…", - "indices": [ - 167, - 190 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "quote_count": 1, - "reply_count": 4, - "retweet_count": 7, - "favorite_count": 29, - "entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/ahQvTYaOcZ", - "expanded_url": "https://x.com/i/web/status/1328399838128467969", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [{ - "tag": null - }] -} -``` - -#### Retweeted Quote Tweet - -``` - { - "created_at": "Thu Feb 06 17:26:44 +0000 2020", - "id": 1225470895902412800, - "id_str": "1225470895902412800", - "text": "RT @AureliaSpecker: 📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses…", - "source": "X for iPhone", - "truncated": false, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "X Dev", - "screen_name": "XDevelopers", - "location": "127.0.0.1", - "url": "https://developer.x.com/en/community", - "description": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "translator_type": "regular", - "protected": false, - "verified": true, - "followers_count": 512292, - "friends_count": 2038, - "listed_count": 1666, - "favourites_count": 2147, - "statuses_count": 3634, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "FFFFFF", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png", - "profile_background_tile": false, - "profile_link_color": "0084B4", - "profile_sidebar_border_color": "FFFFFF", - "profile_sidebar_fill_color": "DDEEF6", - "profile_text_color": "333333", - "profile_use_background_image": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1594913664", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "retweeted_status": { - "created_at": "Tue Feb 04 15:01:25 +0000 2020", - "id": 1224709550214873000, - "id_str": "1224709550214873090", - "text": "📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that u… https://t.co/cAepHunkFp", - "display_text_range": [ - 0, - 140 - ], - "source": "X Web App", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 1102321381, - "id_str": "1102321381", - "name": "Aurelia Specker", - "screen_name": "AureliaSpecker", - "location": "London, UK", - "url": null, - "description": "devrel @TwitterUK • Swiss in London • mother of houseplants • personal hairdresser to @_dormrod", - "translator_type": "none", - "protected": false, - "verified": false, - "followers_count": 1032, - "friends_count": 1331, - "listed_count": 26, - "favourites_count": 4979, - "statuses_count": 854, - "created_at": "Fri Jan 18 23:45:43 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "8B542B", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme8/bg.gif", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme8/bg.gif", - "profile_background_tile": false, - "profile_link_color": "5E341C", - "profile_sidebar_border_color": "D9B17E", - "profile_sidebar_fill_color": "EADEAA", - "profile_text_color": "333333", - "profile_use_background_image": true, - "profile_image_url": "http://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/1102321381/1587552672", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "quoted_status_id": 1195000047089389600, - "quoted_status_id_str": "1195000047089389573", - "quoted_status": { - "created_at": "Thu Nov 14 15:26:27 +0000 2019", - "id": 1195000047089389600, - "id_str": "1195000047089389573", - "text": "I wrote a tutorial on how to get bespoke commute information using the X API🚇\n\n#DEVcommunity #Pythontutorial… https://t.co/pL0qJ4vhtE", - "source": "X Web App", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 1102321381, - "id_str": "1102321381", - "name": "Aurelia Specker", - "screen_name": "AureliaSpecker", - "location": "London, UK", - "url": null, - "description": "devrel @TwitterUK • Swiss in London • mother of houseplants • personal hairdresser to @_dormrod", - "translator_type": "none", - "protected": false, - "verified": false, - "followers_count": 1032, - "friends_count": 1331, - "listed_count": 26, - "favourites_count": 4979, - "statuses_count": 854, - "created_at": "Fri Jan 18 23:45:43 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "8B542B", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme8/bg.gif", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme8/bg.gif", - "profile_background_tile": false, - "profile_link_color": "5E341C", - "profile_sidebar_border_color": "D9B17E", - "profile_sidebar_fill_color": "EADEAA", - "profile_text_color": "333333", - "profile_use_background_image": true, - "profile_image_url": "http://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/1102321381/1587552672", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "I wrote a tutorial on how to get bespoke commute information using the X API🚇\n\n#DEVcommunity #Pythontutorial \n\nCheck it out here 👇\nhttps://t.co/sOjXW4YhbN", - "display_text_range": [ - 0, - 160 - ], - "entities": { - "hashtags": [{ - "text": "DEVcommunity", - "indices": [ - 85, - 98 - ] - }, - { - "text": "Pythontutorial", - "indices": [ - 99, - 114 - ] - } - ], - "urls": [{ - "url": "https://t.co/sOjXW4YhbN", - "expanded_url": "https://dev.to/twitterdev/using-the-twitter-api-to-make-your-commute-easier-3od0", - "display_url": "dev.to/twitterdev/usi…", - "unwound": { - "url": "https://dev.to/twitterdev/using-the-twitter-api-to-make-your-commute-easier-3od0", - "status": 200, - "title": null, - "description": null - }, - "indices": [ - 137, - 160 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "quote_count": 4, - "reply_count": 5, - "retweet_count": 31, - "favorite_count": 123, - "entities": { - "hashtags": [{ - "text": "DEVcommunity", - "indices": [ - 85, - 98 - ] - }, - { - "text": "Pythontutorial", - "indices": [ - 99, - 114 - ] - } - ], - "urls": [{ - "url": "https://t.co/pL0qJ4vhtE", - "expanded_url": "https://x.com/i/web/status/1195000047089389573", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 116, - 139 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en" - }, - "quoted_status_permalink": { - "url": "https://t.co/dXrJYvn3hY", - "expanded": "https://x.com/AureliaSpecker/status/1195000047089389573", - "display": "x.com/AureliaSpecker…" - }, - "is_quote_status": true, - "extended_tweet": { - "full_text": "📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses X's new search endpoint 🚇 https://t.co/87XIPZmZBJ\n\n#DEVcommunity #Pythontutorial @XDev @XAPI https://t.co/dXrJYvn3hY", - "display_text_range": [ - 0, - 229 - ], - "entities": { - "hashtags": [{ - "text": "DEVcommunity", - "indices": [ - 176, - 189 - ] - }, - { - "text": "Pythontutorial", - "indices": [ - 190, - 205 - ] - } - ], - "urls": [{ - "url": "https://t.co/87XIPZmZBJ", - "expanded_url": "https://bit.ly/2OrnrCC", - "display_url": "bit.ly/2OrnrCC", - "unwound": { - "url": "https://dev.to/twitterdev/migrate-to-twitter-s-newly-released-labs-recent-search-endpoint-3npe", - "status": 200, - "title": null, - "description": null - }, - "indices": [ - 151, - 174 - ] - }, - { - "url": "https://t.co/dXrJYvn3hY", - "expanded_url": "https://x.com/AureliaSpecker/status/1195000047089389573", - "display_url": "x.com/AureliaSpecker…", - "indices": [ - 230, - 253 - ] - } - ], - "user_mentions": [{ - "screen_name": "XDev", - "name": "X Dev", - "id": 2244994945, - "id_str": "2244994945", - "indices": [ - 206, - 217 - ] - }, - { - "screen_name": "XAPI", - "name": "X API", - "id": 6253282, - "id_str": "6253282", - "indices": [ - 218, - 229 - ] - } - ], - "symbols": [] - } - }, - "quote_count": 2, - "reply_count": 0, - "retweet_count": 12, - "favorite_count": 43, - "entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/cAepHunkFp", - "expanded_url": "https://x.com/i/web/status/1224709550214873090", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en" - }, - "quoted_status_id": 1195000047089389600, - "quoted_status_id_str": "1195000047089389573", - "quoted_status": { - "created_at": "Thu Nov 14 15:26:27 +0000 2019", - "id": 1195000047089389600, - "id_str": "1195000047089389573", - "text": "I wrote a tutorial on how to get bespoke commute information using the X API🚇\n\n#DEVcommunity #Pythontutorial… https://t.co/pL0qJ4vhtE", - "source": "X Web App", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 1102321381, - "id_str": "1102321381", - "name": "Aurelia Specker", - "screen_name": "AureliaSpecker", - "location": "London, UK", - "url": null, - "description": "devrel @TwitterUK • Swiss in London • mother of houseplants • personal hairdresser to @_dormrod", - "translator_type": "none", - "protected": false, - "verified": false, - "followers_count": 1032, - "friends_count": 1331, - "listed_count": 26, - "favourites_count": 4979, - "statuses_count": 854, - "created_at": "Fri Jan 18 23:45:43 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "8B542B", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme8/bg.gif", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme8/bg.gif", - "profile_background_tile": false, - "profile_link_color": "5E341C", - "profile_sidebar_border_color": "D9B17E", - "profile_sidebar_fill_color": "EADEAA", - "profile_text_color": "333333", - "profile_use_background_image": true, - "profile_image_url": "http://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/1102321381/1587552672", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "I wrote a tutorial on how to get bespoke commute information using the X API🚇\n\n#DEVcommunity #Pythontutorial \n\nCheck it out here 👇\nhttps://t.co/sOjXW4YhbN", - "display_text_range": [ - 0, - 160 - ], - "entities": { - "hashtags": [{ - "text": "DEVcommunity", - "indices": [ - 85, - 98 - ] - }, - { - "text": "Pythontutorial", - "indices": [ - 99, - 114 - ] - } - ], - "urls": [{ - "url": "https://t.co/sOjXW4YhbN", - "expanded_url": "https://dev.to/twitterdev/using-the-twitter-api-to-make-your-commute-easier-3od0", - "display_url": "dev.to/twitterdev/usi…", - "unwound": { - "url": "https://dev.to/twitterdev/using-the-twitter-api-to-make-your-commute-easier-3od0", - "status": 200, - "title": null, - "description": null - }, - "indices": [ - 137, - 160 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "quote_count": 4, - "reply_count": 5, - "retweet_count": 31, - "favorite_count": 123, - "entities": { - "hashtags": [{ - "text": "DEVcommunity", - "indices": [ - 85, - 98 - ] - }, - { - "text": "Pythontutorial", - "indices": [ - 99, - 114 - ] - } - ], - "urls": [{ - "url": "https://t.co/pL0qJ4vhtE", - "expanded_url": "https://x.com/i/web/status/1195000047089389573", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 116, - 139 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en" - }, - "quoted_status_permalink": { - "url": "https://t.co/dXrJYvn3hY", - "expanded": "https://x.com/AureliaSpecker/status/1195000047089389573", - "display": "x.com/AureliaSpecker…" - }, - "is_quote_status": true, - "quote_count": 0, - "reply_count": 0, - "retweet_count": 0, - "favorite_count": 0, - "entities": { - "hashtags": [], - "urls": [], - "user_mentions": [{ - "screen_name": "AureliaSpecker", - "name": "Aurelia Specker", - "id": 1102321381, - "id_str": "1102321381", - "indices": [ - 3, - 18 - ] - }], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [{ - "tag": null - }] - } - ``` -## Enterprise Activity Streams data objects - - -Interested in learning more about how the Activity Streams data format maps to the X API v2 format? - -Check out our comparison guide: [Activity Streams compared to X API v2](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) - - -Please note: It is highly recommended to use the [Enriched Native](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-tweet-object) format for enterprise data APIs.  - -* The Enriched Native format includes all new metadata since 2017, such as [poll metadata](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#poll-metadata), and additional metrics such as reply\_count and quote\_count. - -* Activity Streams format has not been updated with new metadata or enrichments since the [character update](https://blog.x.com/official/en_us/topics/product/2017/Giving-you-more-characters-to-express-yourself.html) in 2017. - - -### Activity Object - -Activity Streams is an object schema translation of X's [original data format](https://developer.x.comhttps://developer.x.com/en/docs/x-api/v1/data-dictionary/overview) created by Gnip to 'normalize the format' of Post data and other social media data using the third party [Activity Base Schema described here](https://activitystrea.ms/head/activity-schema.html). Posts are normalized into the activity streams schema, including: note, person, place and service object types as nested objects.  Posts can have other nested Post activity obejcts for Retweets, or others including twitter\_quoted\_status, long_object. - -The base level object type "activity" is similar to the [Post base level object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-tweet-object) of the native enriched format.  Example payloads in activity streams format can be found [here](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#activity-streams-payload-examples). - -#### Data Dictionary - -Below you will find the data dictionary for these ‘root-level’ "activity" attributes, as well as links to child object data dictionaries. - -| | | | -| :--- | :--- | :--- | -| Attribute | Type | Description | -| id | string | A unique IRI for the post. In more detail, "tag" is the scheme, "search.x.com" represents the domain for the scheme, and 2005 is when the scheme was derived.
When storing Posts, this should be used as the unique identifier or primary key.
"id": "tag:search.x.com,2005:1050118621198921728" | -| objectType | string | Type of object, always set to "activity"
"objectType": "activity" | -| object | object | An object representing post being posted or shared.
For Retweets, this will contain an entire "activity", with the pertinent fields described in this schema.
For Original posts, this will contain a "note" object, with the fields described here.
"object":
"object":
"objectType": "note",
"id": "object:search.x.com,2005:1050118621198921728",
"summary": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin t… https://t.co/MkGjXf9aXm",
"link": "http://x.com/API/statuses/1050118621198921728",
"postedTime": "2018-10-10T20:19:24.000Z"
| -| long_object | object | An object representing the full text body if the post text extends beyond 140 characters.


"long_object":
"body": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin tone modifiers 👍🏻👍🏽👍🏿. This is now reflected in Twitter-Text, our Open Source library. \\n\\nUsing Twitter-Text? See the forum post for detail: https://t.co/Nx1XZmRCXA",
"display\_text\_range": \[
0,
277
\],
"twitter_entities":
"hashtags": \[\],
"urls": \[

"url": "https://t.co/Nx1XZmRCXA",
"expanded_url": "https://devcommunity.x.com/t/new-update-to-the-twitter-text-library-emoji-character-count/114607",
"display_url": "devcommunity.com/t/new-update-t…",
"indices": \[
254,
277
\]

\],
"user_mentions": \[\],
"symbols": \[\]

| -| display\_text\_range | array | if the post text extends beyond 140 characters.


"display\_text\_range": \[
0,
142
\] | -| verb | string | [The type of action being taken by the user.
Posts, "post"
Retweets, "share"
Deleted Posts, "delete"
The verb is the proper way to distinguish between a Tweet and a true Retweet. However, this only applies to true retweets, and not modified or quoted Tweets, which don't use X Retweet functionality. For a description of AS verbs](http://activitystrea.ms/head/activity-schema.html#verbs) [click here](http://activitystrea.ms/head/activity-schema.html#verbs).
For Deletes, note that only a limited number of fields will be included, as shown in the sample payload below.
"verb": "post" | -| postedTime | date (ISO 8601) | The time the action occurred, e.g. the time the post was posted.


"postedTime": "2018-10-10T20:19:24.000Z" | -| generator | object | An object representing the utility used to post the post. This will contain the name ("displayName") and a link ("link") for the source application generating the Post.
"generator":
"displayName": "X Web Client",
"link": "http://x.com"
| -| provider | object | A JSON object representing the provider of the activity. This will contain an objectType ("service"), the name of the provider ("displayName"), and a link to the provider's website ("link").
"provider":

"objectType": "service",
"displayName": "X",
"link": "http://www.x.com"
| -| link | string | A Permalink for the post.
"link": "http://x.com/API/statuses/1050118621198921728" | -| body | string | The post text.

In Retweets, note that X modifies the value of the body at the root level by adding "RT @username" at the beginning, and by truncating the original text and adding an ellipsis at the end. Thus, for Retweets, your app should look at the object.body to ensure that it is extracting the non-modified text of the original Post (being retweeted).
"body": "With Cardiff, Crystal Palace, and Hull City joining the EPL from the Championship it will be a great relegation battle at the end." | -| display\_text\_range | array | Describes the range of characters within the body text that indicates the displayed Post. Posts with leading @mentions will start at more than 0 and Posts with attached media or that extened beyond 140 characters will indicate the display\_text\_range in the long_object.

"display\_text\_range": \[
14,
42
\]
or
"long_object":
"display\_text\_range": \[
0,
277
\]... | -| actor | object | [An object representing the x user who posted. The Actor Object refers to a X User, and contains all metadata relevant to that user.
See](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#actor-object) [actor object details](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#actor-object) | -| inReplyTo | object | A JSON object referring to the Post being replied to, if applicable. Contains a link to the Post.
"inReplyTo":

"link": "http:\\/\\/x.com\\/GOP\\/statuses\\/349573991561838593"
| -| location | object | [A JSON object representing the X "Place" where the post was created. This is an object passed through from the X platform.

See](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#location-object) [location object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#location-object) | -| twitter_entities | object | The entities object from X's data format which contains lists of urls, mentions and hashtags. Please reference the X documentation on Entities here Note that in Retweets, X may truncate the values of entities that it extracts at the root level. So, for Retweets, your app should look at object.twitter_entities to ensure that you are using non-truncated values.

See twitter_entities object details | -| twitter\_extended\_entities | object | An object from X's native data format containing "media". This will be present for any post where the twitter_entities object has data present in the "media" field, and will include multiple photos where present in the post. Note that this is the correct location to retrieve media information for multi-photo posts.

Multiple photos are represented by comma-separated JSON objects within the "media" array.

See [twitter\_extended\_entities object details](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-extended-entities-object) | -| gnip | object | An object added to the activity payload to indicate the matching rules, and added enriched data based on enrichments active on the stream or product.

See [gnip object details](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#gnip-object) | -| edit_history | Object | Unique identifiers indicating all versions of a Post. For Posts with no edits, there will be one ID. For Posts with an edit history, there will be multiple IDs, arranged in ascending order reflecting the order of edits, with the most recent version in the last position of the array. 

The Post IDs can be used to hydrate and view previous versions of a Post.

Example:

edit_history":
"initial\_tweet\_id": "1283764123"
"edit\_tweet\_ids": \["1283764123", "1394263866"\]
| -| edit_controls | Object | When present, indicates how long a Post is still editable for and the number of remaining edits. Posts are only editable for the first 30 minutes after creation and can be edited up to five times. 

The Post IDs can be used to hydrate and view previous versions of a Post.

Example:

"edit_controls":
"editable\_until\_ms": 123
"edits_remaining": 3
| -| editable | Boolean | When present, indicates if a Post was eligible for edit when published. This field is not dynamic and won't toggle from True to False when a Post reaches its editable time limit, or maximum number of edits. The following Post features will cause this field to be false:

* Posts is promoted
* Post has a poll
* Post is a non-self-thread reply
* Post is a retweet (note that Quote Tweets are eligible for edit)
* Post is nullcast
* Community Post
* Superfollow Post
* Collaborative Post | - -#### Additional Post attributes - -| Attribute | Type | Description | -| :--- | :--- | :--- | -| twitter_lang | string | | -| favoritesCount | int | _Nullable._ Indicates approximately how many times this Post has been liked by X users.

"favoritesCount":298 | -| retweetCount | int | Number of times this Post has been retweeted. Example:

"retweetCount":153 | - -#### Deprecated Attributes - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| geo | object | Point location where the Post was created. | -| twitter\_filter\_level | string | Deprecated field left in for non breaking change | - -#### Nested Post activity obejcts - -In several cases, a Post object will included other nested Posts.  If you are working with nested objects, then that JSON payload will contain multiple objects, and each Post object may contain its own objects. The root-level object will contain information on the type of action taken, i.e. whether it is a Retweet or a Quote Tweet, and may also contain an object that describes the 'original' Post being shared. Extended Posts will include a nested extended object that extends beyond 140 characters, which was used to prevent breaking changes when the update was made in 2017. Each nested object dictionary is described below. - -**Retweets** - -Activity streams format of Retweets includes a nested object with the type "activity" and the verb "note" to represent the original Post being Retweeted. - -``` -{ - "id": "tag:search.x.com,2005:222222222222", - "objectType": "activity", - "verb": "share", - "body": "RT @TheOriginalTweeter: Coffee and art ☕️", - "actor": { - "displayName": "TheRetweeter" - }, - "object": { - "id": "tag:search.x.com,2005:11111111111", - "objectType": "activity", - "verb": "post", - "body": "Coffee and art ☕️", - "actor": { - "displayName": "TheOriginalTweeter" - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:11111111111", - "summary": "Coffee and art ☕️", - "link": "http://x.com/originaltweeter/statuses/11111111111", - "postedTime": "2020-12-04T11:00:01.000Z" - }, - "twitter_entities": {}, - "twitter_extended_entities": {} - }, - "twitter_entities": {}, - "twitter_extended_entities": {}, - "gnip": {} -} -``` - -**X quoted status** - -Activity streams format embeded quote Tweets - - `{ - "id": "tag:search.x.com,2005:222222222222", - "objectType": "activity", - "verb": "post", - "body": "Quoting a Tweet: https://t.co/mxiFJ59FlB", - "actor": { - "displayName": "TheQuoter2" - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:111111111", - "summary": "https://t.co/mxiFJ59FlB" - }, - "twitter_entities": {}, - "twitter_extended_entities": {}, - "gnip": {}, - "twitter_quoted_status": { - "id": "tag:search.x.com,2005:111111111", - "objectType": "activity", - "verb": "post", - "body": "console.log('Happy birthday, JavaScript!');", - "actor": { - "displayName": "TheOriginalTweeter" - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:111111111" - }, - "twitter_entities": {} - } -}` - -Retweeted Quote Tweet: - -``` - { - "id": "tag:search.x.com,2005:1293612267087384577", - "objectType": "activity", - "verb": "share", - "postedTime": "2020-08-12T18:16:13.000Z", - "generator": {}, - "provider": {}, - "link": "http://x.com/XDevelopers/statuses/1293612267087384577", - "body": "RT @compston: So excited to make this first set of endpoints available - many more to come before we're done. The @XDevelopers #DevRel team…", - "actor": {}, - "object": {}, - "favoritesCount": 0, - "twitter_entities": {}, - "twitter_lang": "en", - "retweetCount": 13, - "gnip": {}, - "twitter_filter_level": "low", - "twitter_quoted_status": {} - } - ``` - -#### Long object - -Activity streams format of the extended_tweet - -``` -{ - "id": "tag:search.x.com,2005:1050118621198921728", - "objectType": "activity", - "verb": "post", - "postedTime": "2018-10-10T20:19:24.000Z", - "generator": { - "displayName": "X Web Client", - "link": "http://x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/API/statuses/1050118621198921728", - "body": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin t… https://t.co/MkGjXf9aXm", - "long_object": { - "body": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin tone modifiers 👍🏻👍🏽👍🏿. This is now reflected in Twitter-Text, our Open Source library. \n\nUsing Twitter-Text? See the forum post for detail: https://t.co/Nx1XZmRCXA", - "display_text_range": [ - 0, - 277 - ], - "twitter_entities": {see twitter_entities object}, - "actor": {see actor object}, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1050118621198921728", - "summary": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin t… https://t.co/MkGjXf9aXm", - "link": "http://x.com/API/statuses/1050118621198921728", - "postedTime": "2018-10-10T20:19:24.000Z" - }, - "favoritesCount": 298, - "twitter_entities": {see twitter_entities object}, - "twitter_lang": "en", - "retweetCount": 153, - "gnip": {see gnip object}, - "twitter_filter_level": "low" -} -``` - -### Actor object - -The actor object contains X User account metadata that describes the X User which created the activity. - -#### Data Dictionary - -| Attribute | Type | Description | -| :--- | :--- | :--- | -| objectType | string | **"objectType":** "person" | -| id | string | The string representation of the unique identifier for this author. Example:

"id:x.com:2244994945" | -| link | | "http://www.x.com/XDeveloeprs | -| displayName | String | The name of the user, as they’ve defined it. Not necessarily a person’s name. Typically capped at 50 characters, but subject to change. Example:

**"displayName":** "XDevelopers" | -| preferredUsername | string | The screen name, handle, or alias that this user identifies themselves with. Unique but subject to change. Use `id` as a user identifier whenever possible. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names. Example:

**"preferredUsername":** "XDevelopers" | -| location | object | **        "location": **

**"objectType":** "place"**,**

**"displayName":** "127.0.0.1"

**        }** | -| links | array | _Nullable_ . A URL provided by the user in association with their profile. Example:

**       "links": \[**

**          \{ **

**"href":** "https://developer.x.com/en/community"**,**

**"rel":** "me"

**          }**

**        \]** | -| summary | string | _Nullable_ . The user-defined UTF-8 string describing their account. Example:

**"summary":** "The voice of the #XDevelopers team..." | -| protected | Boolean | When true, indicates that this user has chosen to protect their Posts. See [About Public and Protected Posts](https://support.x.com/articles/14016-about-public-and-protected-tweets). Example:

"protected": true | -| verified | Boolean | When true, indicates that the user has a verified account. See [Verified Accounts](https://support.x.com/articles/119135-faqs-about-verified-accounts) . Example:

"verified": false | -| followersCount | Int | The number of followers this account currently has. Under certain conditions of duress, this field will temporarily indicate “0”. Example:

"followers_count": 21 | -| friendsCount | Int | The number of users this account is following (AKA their “followings”). Under certain conditions of duress, this field will temporarily indicate “0”. Example:

"friends_count": 32 | -| listedCount | Int | The number of public lists that this user is a member of. Example:

"listed_count": 9274 | -| favoritesCount | Int | The number of Posts this user has liked in the account’s lifetime. British spelling used in the field name for historical reasons. Example:

"favourites_count": 13 | -| statusesCount | Int | The number of Posts (including retweets) issued by the user. Example:

"statuses_count": 42 | -| postedTime | date | The UTC datetime that the user account was created on X. Example:

**"postedTime":** "2013-12-14T04:35:55.036Z" | -| image | string | A HTTPS-based URL pointing to the user’s profile image. Example:

**"image":** "https://pbs.twimg.com/profile\_images/1283786620521652229/lEODkLTh\_normal.jpg" | - -#### No longer supported (deprecated) attributes - -| Field | Type | Description | -| :--- | :--- | :--- | -| utcOffset | null | Value will be set to null. Still available via [GET account/settings](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-settings) | -| twitterTimeZone | null | Value will be set to null. Still available via [GET account/settings](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-settings) as tzinfo_name | -| languages | null | Value will be set to null. Still available via [GET account/settings](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-settings) as language | - -#### Examples: - - ``` - "actor": { - "objectType": "person", - "id": "id:twitter.com:2244994945", - "link": "http://www.x.com/XDevelopers", - "displayName": "X Dev", - "postedTime": "2013-12-14T04:35:55.036Z", - "image": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "summary": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "friendsCount": 2039, - "followersCount": 512197, - "listedCount": 1662, - "statusesCount": 3632, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "XDevelopers", - "languages": [], - "links": [ - { - "href": "https://developer.x.com/en/community", - "rel": "me" - } - ], - "location": { - "objectType": "place", - "displayName": "127.0.0.1" - }, - "favoritesCount": 2147 - } -``` - - -``` -"actor": { - "objectType": "person", - "id": "id:twitter.com:6253282", - "link": "http://www.x.com/API", - "displayName": "X API", - "postedTime": "2007-05-23T06:01:13.000Z", - "image": "https://pbs.twimg.com/profile_images/942858479592554497/BbazLO9L_normal.jpg", - "summary": "Tweets about changes and service issues. Follow @XDevelopers for more.", - "friendsCount": 39, - "followersCount": 6054164, - "listedCount": 12285, - "statusesCount": 3689, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "API", - "languages": [ - - ], - "links": [ - { - "href": "https://developer.x.com", - "rel": "me" - } - ], - "favoritesCount": 4 - } - ``` - - -### Location Object - -Location obejcts can exist within the actor obejct set on the X account level or within the profileLocations object of the [gnip object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#gnip-object). Location objects have a place object type and can have a name, address, or geo coordinates. Location objects are similar to [Geo](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-geo-objects) in native enriched format. - -#### Location data dictionary - -| Field | Type | Description | -| :--- | :--- | :--- | -| objectType | string | See [here](http://activitystrea.ms/head/activity-schema.html#place) for more detailed information. Example:

**"objectType":** "place" | -| displayName | string | **The full name of the location.

****"displayName":** "United States" | -| name | string | Name of the location from X's place JSON format. | -| link | string | A link to the full X JSON representation of the place.

**"link":** "https://api.x.com/1.1/geo/id/27c45d804c777999.json" | -| geo | object | The geo coordintates object from X.  Either a polygon, or point.

See [geo](https://developer.x.com/en/docs/x-api/v1/data-dictionary/object-model/geo#coordinates) | -| countryCode | String | Shortened country code representing the country containing this place. Example:

**"countryCode": "US** | -| country | String | Name of the country containing this place. Example:

**"country": **"United States" | - -#### profileLocations derived obejcts - -| | | | -| :--- | :--- | :--- | -| Field | Type | Description | -| address | object | Within profileLocation location object within the [gnip object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#gnip-object).  Address of location derived by the [profile geo enrichement](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo).  Level of granularity will vary. 

**"address": \{**

**          "country": **"United States"**,**

**          "countryCode": **"US"**,**

**          "locality": **"Providence"**,**

**          "region": **"Rhode Island"**,**

**          "subRegion": **"Providence County"

**        }** | -| geo | object | Within profileLocation location object within the [gnip objec](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#gnip-object)t. Centroid coordinates of the location derived by the [profile geo enrichement](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo).

**"geo": \{**

**          "coordinates": \[**

-98.5**,**

39.76

**          \],**

**          "type": **"point"

**        }** | - -**Examples** - - ``` - "location": { - "objectType": "place", - "displayName": "Kansas, USA", - "name": "Kansas", - "country_code": "United States", - "twitter_country_code": "US", - "twitter_place_type": "admin", - "link": "https://api.x.com/1.1/geo/id/27c45d804c777999.json", - "geo": { - "type": "Polygon", - "coordinates": [ - [ - [ - -102.051769, - 36.99311 - ], - [ - -102.051769, - 40.003282 - ], - [ - -94.588081, - 40.003282 - ], - [ - -94.588081, - 36.99311 - ] - ] - ] - } - ``` - -``` - "location": { - "objectType": "place", - "displayName": "California, USA" - } - ``` - -### X entities object - -For Activity streams format, the twitter_entities is the same format and data dictionary shown on the native enriched format [entities object here](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#entities-object). - -#### Example: - -``` -"twitter_entities": { - "hashtags": [{ - "text": "API", - "indices": [ - 228, - 239 - ] - }], - "urls": [{ - "url": "https://t.co/r6z6CI7kEy", - "expanded_url": "https://devcommunity.x.com/t/retiring-labs-v2-recent-search-and-hide-replies/145795", - "display_url": "devcommunity.com/t/retiring-lab…", - "indices": [ - 250, - 273 - ] - }], - "user_mentions": [], - "symbols": [] -} -``` - -### X extended entities object - -For Activity streams format, the twitter\_extended\_entities is the same format and data dictionary shown on the native enriched format [extended_entities object here](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-extended-entities). - -#### Example: - -``` -"twitter_extended_entities":{ - "media": [{ - "id": 1293565706408038400, - "id_str": "1293565706408038401", - "indices": [ - 219, - 242 - ], - "additional_media_info": { - "monetizable": false - }, - "media_url": "http://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "media_url_https": "https://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "url": "https://t.co/KaFSbjWUA8", - "display_url": "pic.x.com/KaFSbjWUA8", - "expanded_url": "https://x.com/XDevelopers/status/1293593516040269825/video/1", - "type": "video", - "video_info": { - "aspect_ratio": [ - 16, - 9 - ], - "duration_millis": 34875, - "variants": [{ - "bitrate": 256000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/480x270/Fg9lnGGsITO0uq2K.mp4?tag=10" - }, - { - "bitrate": 832000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/640x360/-crbtZE4y8vKN_uF.mp4?tag=10" - }, - { - "content_type": "application/x-mpegURL", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/pl/OvIqQojosF6sMIHR.m3u8?tag=10" - }, - { - "bitrate": 2176000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/1280x720/xkxyb-VPVY4OI0j9.mp4?tag=10" - } - ] - }, - "sizes": { - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "medium": { - "w": 1200, - "h": 675, - "resize": "fit" - }, - "small": { - "w": 680, - "h": 383, - "resize": "fit" - }, - "large": { - "w": 1280, - "h": 720, - "resize": "fit" - } - } - }] -} -``` -### Gnip object - - -The gnip object, within Activity streams format, contains the metadata added by the active enrichments, as well as indication of the matching rules for the activity. - -#### Data dictionary - -| | | | -| :--- | :--- | :--- | -| **Field** | **Type** | **Description** | -| matching_rules | array | Contains an array of matching rule objects which indicate the rule which the activity matches on.
**"matching_rules": \[**

**      \{**

**        "tag": null,**

**"id":** 1026514022567358500**,**

**"id_str":** "1026514022567358464"

**      }**

**    \]** | -| urls | array | Contains an array of the links within the activity, and the expanded url metadata for the ***URL unwinding enrichement

**    "urls": \[**

**      \{**

**"url":** "https://t.co/tGQqNxxyhU"**,**

**"expanded_url":** "https://www.youtube.com/channel/UCwUxW2CV2p5mzjMBqvqLzJA"**,**

**"expanded_status":** 200**,**

**"expanded\_url\_title":** "Birdys Daughter"**,**

**"expanded\_url\_description":** "Premium, single-origin, handpicked Jamaica Blue Mountain Coffee"

**      }**

**    \]** | -| profileLocations | array of location objects | Contains the derived location object from the Profile Geo enrichment

**    "profileLocations": \[**

**      \{**

**        "address": \{**

**"country":** "Canada"**,**

**"countryCode":** "CA"**,**

**"locality":** "Toronto"**,**

**"region":** "Ontario"

**        },**

**"displayName":** "Toronto, Ontario, Canada"**,**

**        "geo": \{**

**          "coordinates": \[**

-79.4163**,**

43.70011

**          \],**

**"type":** "point"

**        },**

**"objectType":** "place"

**      }**

**    \]**

**  }** | - -#### Example: - -```json - "gnip": { - "matching_rules": [ - { - "tag": null - } - ], - "urls": [ - { - "url": "https://t.co/Nx1XZmRCXA", - "expanded_url": "https://devcommunity.x.com/t/new-update-to-the-twitter-text-library-emoji-character-count/114607", - "expanded_status": 200, - "expanded_url_title": null, - "expanded_url_description": null - } - ] - } - ``` -#### Activity streams payload examples - - -Post activity - -``` -{ - "id": "tag:search.x.com,2005:1307025659294674945", - "objectType": "activity", - "verb": "post", - "postedTime": "2020-09-18T18:36:15.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/XDevelopers/statuses/1307025659294674945", - "body": "Here’s an article that highlights the updates in the new Tweet payload v2 https://t.co/oeF3ZHeKQQ", - "actor": { - "objectType": "person", - "id": "id:twitter.com:2244994945", - "link": "http://www.x.com/XDevelopers", - "displayName": "X Dev", - "postedTime": "2013-12-14T04:35:55.036Z", - "image": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "summary": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "friendsCount": 2038, - "followersCount": 512292, - "listedCount": 1666, - "statusesCount": 3634, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "XDevelopers", - "languages": [], - "links": [{ - "href": "https://developer.x.com/en/community", - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "127.0.0.1" - }, - "favoritesCount": 2147 - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1307025659294674945", - "summary": "Here’s an article that highlights the updates in the new Tweet payload v2 https://t.co/oeF3ZHeKQQ", - "link": "http://x.com/XDevelopers/statuses/1307025659294674945", - "postedTime": "2020-09-18T18:36:15.000Z" - }, - "inReplyTo": { - "link": "http://x.com/XDevelopers/statuses/1304102743196356610" - }, - "favoritesCount": 70, - "twitter_entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/oeF3ZHeKQQ", - "expanded_url": "https://dev.to/twitterdev/understanding-the-new-tweet-payload-in-the-twitter-api-v2-1fg5", - "display_url": "dev.to/twitterdev/und…", - "indices": [ - 74, - 97 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "twitter_lang": "en", - "retweetCount": 11, - "gnip": { - "matching_rules": [{ - "tag": null - }], - "urls": [{ - "url": "https://t.co/oeF3ZHeKQQ", - "expanded_url": "https://dev.to/twitterdev/understanding-the-new-tweet-payload-in-the-twitter-api-v2-1fg5", - "expanded_status": 200, - "expanded_url_title": "Understanding the new Tweet payload in the X API v2", - "expanded_url_description": "X recently announced the new X API v2, rebuilt from the ground up to deliver new features..." - }] - }, - "twitter_filter_level": "low" -} -``` - -Reply Post activity - -``` -{ - "id": "tag:search.x.com,2005:1296887316556980230", - "objectType": "activity", - "verb": "post", - "postedTime": "2020-08-21T19:10:05.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/XDevelopers/statuses/1296887316556980230", - "body": "See how @PennMedCDH are using X data to understand the COVID-19 health crisis 📊\n\nhttps://t.co/1tdA8uDWes", - "actor": { - "objectType": "person", - "id": "id:twitter.com:2244994945", - "link": "http://www.x.com/XDevelopers", - "displayName": "X Dev", - "postedTime": "2013-12-14T04:35:55.036Z", - "image": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "summary": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #API.", - "friendsCount": 2038, - "followersCount": 512292, - "listedCount": 1666, - "statusesCount": 3634, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "XDevelopers", - "languages": [], - "links": [{ - "href": "https://developer.x.com/en/community", - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "127.0.0.1" - }, - "favoritesCount": 2147 - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1296887316556980230", - "summary": "See how @PennMedCDH are using X data to understand the COVID-19 health crisis 📊\n\nhttps://t.co/1tdA8uDWes", - "link": "http://x.com/XDevelopers/statuses/1296887316556980230", - "postedTime": "2020-08-21T19:10:05.000Z" - }, - "inReplyTo": { - "link": "http://x.com/XDevelopers/statuses/1296887091901718529" - }, - "favoritesCount": 26, - "twitter_entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/1tdA8uDWes", - "expanded_url": "https://developer.x.com/en/use-cases/success-stories/penn", - "display_url": "developer.x.com/en/use-cases/s…", - "indices": [ - 87, - 110 - ] - }], - "user_mentions": [{ - "screen_name": "PennMedCDH", - "name": "Penn Med CDH", - "id": 1615654896, - "id_str": "1615654896", - "indices": [ - 8, - 19 - ] - }], - "symbols": [] - }, - "twitter_lang": "en", - "retweetCount": 9, - "gnip": { - "matching_rules": [{ - "tag": null - }], - "urls": [{ - "url": "https://t.co/1tdA8uDWes", - "expanded_url": "https://developer.x.com/en/use-cases/success-stories/penn", - "expanded_status": 200, - "expanded_url_title": "Penn Medicine Center for Digital Health", - "expanded_url_description": "Penn Med Center for Digital Health has created a COVID-19 X map that includes charts detailing sentiment, symptoms reported, state-by-state data cuts, and border data on the COVID-19 outbreak. In addition, their Penn Med With You initiative uses aggregate regional information from X to inform their website and text-messaging service. The service uses this information to disseminate relevant and timely resources." - }] - }, - "twitter_filter_level": "low" -} -``` - -Post activity with long_object - -``` -{ - "id": "tag:search.x.com,2005:1296121314218897408", - "objectType": "activity", - "verb": "post", - "postedTime": "2020-08-19T16:26:16.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/XDevelopers/statuses/1296121314218897408", - "body": "The hide replies endpoint is launching today! \n\nDevelopers can hide replies to Tweets - a crucial way developers ca… https://t.co/VyfXs1RTXn", - "long_object": { - "body": "The hide replies endpoint is launching today! \n\nDevelopers can hide replies to Tweets - a crucial way developers can help improve the health of the public conversation using the #XAPI.\n\nhttps://t.co/khXhTurm9x", - "display_text_range": [ - 0, - 215 - ], - "twitter_entities": { - "hashtags": [{ - "text": "API", - "indices": [ - 178, - 189 - ] - }], - "urls": [{ - "url": "https://t.co/khXhTurm9x", - "expanded_url": "https://devcommunity.x.com/t/hide-replies-now-available-in-the-new-twitter-api/140996", - "display_url": "devcommunity.com/t/hide-replies…", - "indices": [ - 192, - 215 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "actor": { - "objectType": "person", - "id": "id:twitter.com:2244994945", - "link": "http://www.x.com/XDevelopers", - "displayName": "X Dev", - "postedTime": "2013-12-14T04:35:55.036Z", - "image": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "summary": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "friendsCount": 2038, - "followersCount": 512292, - "listedCount": 1666, - "statusesCount": 3634, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "XDevelopers", - "languages": [], - "links": [{ - "href": "https://developer.x.com/en/community", - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "127.0.0.1" - }, - "favoritesCount": 2147 - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1296121314218897408", - "summary": "The hide replies endpoint is launching today! \n\nDevelopers can hide replies to Tweets - a crucial way developers ca… https://t.co/VyfXs1RTXn", - "link": "http://x.com/XDevelopers/statuses/1296121314218897408", - "postedTime": "2020-08-19T16:26:16.000Z" - }, - "favoritesCount": 172, - "twitter_entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/VyfXs1RTXn", - "expanded_url": "https://x.com/i/web/status/1296121314218897408", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "twitter_lang": "en", - "retweetCount": 54, - "gnip": { - "matching_rules": [{ - "tag": null - }], - "urls": [{ - "url": "https://t.co/khXhTurm9x", - "expanded_url": "https://devcommunity.x.com/t/hide-replies-now-available-in-the-new-twitter-api/140996", - "expanded_status": 200, - "expanded_url_title": "Hide replies now available in the new X API", - "expanded_url_description": "Today, we’re happy to announce the general availability of the hide replies endpoint in the new X API. The hide replies endpoint allows you to build tools that help people hide or unhide replies to their Tweets. People manage their replies for many reasons, including to give less attention to comments that are abusive, distracting, misleading, or to make conversations more engaging. Through this endpoint, you can build tools to help people on X hide or unhide replies faster and more..." - }] - }, - "twitter_filter_level": "low" -} -``` - - -Post activity with `twitter_extended_entities` - -``` -{ - "id": "tag:search.x.com,2005:1293593516040269825", - "objectType": "activity", - "verb": "post", - "postedTime": "2020-08-12T17:01:42.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/XDevelopers/statuses/1293593516040269825", - "body": "It’s finally here! 🥁 Say hello to the new #XAPI.\n\nWe’re rebuilding the X API v2 from the ground up to b… https://t.co/UeCndQGMjx", - "long_object": { - "body": "It’s finally here! 🥁 Say hello to the new #XAPI.\n\nWe’re rebuilding the X API v2 from the ground up to better serve our developer community. And today’s launch is only the beginning.\n\nhttps://t.co/32VrwpGaJw https://t.co/KaFSbjWUA8", - "display_text_range": [ - 0, - 218 - ], - "twitter_entities": { - "hashtags": [{ - "text": "API", - "indices": [ - 42, - 53 - ] - }], - "urls": [{ - "url": "https://t.co/32VrwpGaJw", - "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/introducing_new_twitter_api.html", - "display_url": "blog.x.com/developer/en_u…", - "indices": [ - 195, - 218 - ] - }], - "user_mentions": [], - "symbols": [], - "media": [{ - "id": 1293565706408038400, - "id_str": "1293565706408038401", - "indices": [ - 219, - 242 - ], - "additional_media_info": { - "monetizable": false - }, - "media_url": "http://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "media_url_https": "https://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "url": "https://t.co/KaFSbjWUA8", - "display_url": "pic.x.com/KaFSbjWUA8", - "expanded_url": "https://x.com/XDevelopers/status/1293593516040269825/video/1", - "type": "video", - "video_info": { - "aspect_ratio": [ - 16, - 9 - ], - "duration_millis": 34875, - "variants": [{ - "bitrate": 256000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/480x270/Fg9lnGGsITO0uq2K.mp4?tag=10" - }, - { - "bitrate": 832000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/640x360/-crbtZE4y8vKN_uF.mp4?tag=10" - }, - { - "content_type": "application/x-mpegURL", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/pl/OvIqQojosF6sMIHR.m3u8?tag=10" - }, - { - "bitrate": 2176000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/1280x720/xkxyb-VPVY4OI0j9.mp4?tag=10" - } - ] - }, - "sizes": { - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "medium": { - "w": 1200, - "h": 675, - "resize": "fit" - }, - "small": { - "w": 680, - "h": 383, - "resize": "fit" - }, - "large": { - "w": 1280, - "h": 720, - "resize": "fit" - } - } - }] - }, - "twitter_extended_entities": { - "media": [{ - "id": 1293565706408038400, - "id_str": "1293565706408038401", - "indices": [ - 219, - 242 - ], - "additional_media_info": { - "monetizable": false - }, - "media_url": "http://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "media_url_https": "https://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "url": "https://t.co/KaFSbjWUA8", - "display_url": "pic.x.com/KaFSbjWUA8", - "expanded_url": "https://x.com/XDevelopers/status/1293593516040269825/video/1", - "type": "video", - "video_info": { - "aspect_ratio": [ - 16, - 9 - ], - "duration_millis": 34875, - "variants": [{ - "bitrate": 256000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/480x270/Fg9lnGGsITO0uq2K.mp4?tag=10" - }, - { - "bitrate": 832000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/640x360/-crbtZE4y8vKN_uF.mp4?tag=10" - }, - { - "content_type": "application/x-mpegURL", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/pl/OvIqQojosF6sMIHR.m3u8?tag=10" - }, - { - "bitrate": 2176000, - "content_type": "video/mp4", - "url": "https://video.twimg.com/ext_tw_video/1293565706408038401/pu/vid/1280x720/xkxyb-VPVY4OI0j9.mp4?tag=10" - } - ] - }, - "sizes": { - "thumb": { - "w": 150, - "h": 150, - "resize": "crop" - }, - "medium": { - "w": 1200, - "h": 675, - "resize": "fit" - }, - "small": { - "w": 680, - "h": 383, - "resize": "fit" - }, - "large": { - "w": 1280, - "h": 720, - "resize": "fit" - } - } - }] - } - }, - "display_text_range": [ - 0, - 140 - ], - "actor": { - "objectType": "person", - "id": "id:twitter.com:2244994945", - "link": "http://www.x.com/XDevelopers", - "displayName": "X Dev", - "postedTime": "2013-12-14T04:35:55.036Z", - "image": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "summary": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #TwitterAPI.", - "friendsCount": 2038, - "followersCount": 512292, - "listedCount": 1666, - "statusesCount": 3634, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "XDevelopers", - "languages": [], - "links": [{ - "href": "https://developer.x.com/en/community", - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "127.0.0.1" - }, - "favoritesCount": 2147 - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1293593516040269825", - "summary": "It’s finally here! 🥁 Say hello to the new #API.\n\nWe’re rebuilding the X API v2 from the ground up to b… https://t.co/UeCndQGMjx", - "link": "http://x.com/XDevelopers/statuses/1293593516040269825", - "postedTime": "2020-08-12T17:01:42.000Z" - }, - "favoritesCount": 2844, - "twitter_entities": { - "hashtags": [{ - "text": "API", - "indices": [ - 42, - 53 - ] - }], - "urls": [{ - "url": "https://t.co/UeCndQGMjx", - "expanded_url": "https://x.com/i/web/status/1293593516040269825", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "twitter_lang": "en", - "retweetCount": 958, - "gnip": { - "matching_rules": [{ - "tag": null - }], - "urls": [{ - "url": "https://t.co/32VrwpGaJw", - "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/introducing_new_twitter_api.html", - "expanded_status": 200, - "expanded_url_title": "Introducing a new and improved X API", - "expanded_url_description": "Introducing the new X API - rebuilt from the ground up to deliver new features faster so developers can help the world connect to the public conversation happening on X." - }] - }, - "twitter_filter_level": "low" -} -``` - -Retweet activity - -``` -{ - "id": "tag:search.x.com,2005:1229851574555508737", - "objectType": "activity", - "verb": "share", - "postedTime": "2020-02-18T19:33:59.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/XDevelopers/statuses/1229851574555508737", - "body": "RT @suhemparack: I built an Alexa Skill for X using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it out her…", - "actor": { - "objectType": "person", - "id": "id:twitter.com:2244994945", - "link": "http://www.x.com/XDevelopers", - "displayName": "X Dev", - "postedTime": "2013-12-14T04:35:55.036Z", - "image": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "summary": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "friendsCount": 2038, - "followersCount": 512292, - "listedCount": 1666, - "statusesCount": 3634, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "XDevelopers", - "languages": [], - "links": [{ - "href": "https://developer.x.com/en/community", - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "127.0.0.1" - }, - "favoritesCount": 2147 - }, - "object": { - "id": "tag:search.x.com,2005:1229843515603144704", - "objectType": "activity", - "verb": "post", - "postedTime": "2020-02-18T19:01:58.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/suhemparack/statuses/1229843515603144704", - "body": "I built an Alexa Skill for X using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it… https://t.co/RP9NgltX7i", - "long_object": { - "body": "I built an Alexa Skill for X using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it out here 👇\n\nhttps://t.co/l5J8wq748G", - "display_text_range": [ - 0, - 150 - ], - "twitter_entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/l5J8wq748G", - "expanded_url": "https://dev.to/XDevelopers/building-an-alexa-skill-for-twitter-using-alexa-presentation-language-1aj0", - "display_url": "dev.to/twitterdev/bui…", - "indices": [ - 127, - 150 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "actor": { - "objectType": "person", - "id": "id:twitter.com:857699969263964161", - "link": "http://www.x.com/suhemparack", - "displayName": "Suhem Parack", - "postedTime": "2017-04-27T20:56:22.883Z", - "image": "https://pbs.twimg.com/profile_images/1230703695051935747/TbQKe91L_normal.jpg", - "summary": "Developer Relations for Academic Research @X. Talk to me about research with X data. Previously: Amazon Alexa. Views are my own", - "friendsCount": 501, - "followersCount": 732, - "listedCount": 12, - "statusesCount": 458, - "twitterTimeZone": null, - "verified": false, - "utcOffset": null, - "preferredUsername": "suhemparack", - "languages": [], - "links": [{ - "href": "https://developer.x.com", - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "Seattle, WA" - }, - "favoritesCount": 358 - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1229843515603144704", - "summary": "I built an Alexa Skill for X using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it… https://t.co/RP9NgltX7i", - "link": "http://x.com/suhemparack/statuses/1229843515603144704", - "postedTime": "2020-02-18T19:01:58.000Z" - }, - "favoritesCount": 71, - "twitter_entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/RP9NgltX7i", - "expanded_url": "https://x.com/i/web/status/1229843515603144704", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 116, - 139 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "twitter_lang": "en", - "twitter_filter_level": "low" - }, - "favoritesCount": 0, - "twitter_entities": { - "hashtags": [], - "urls": [], - "user_mentions": [{ - "screen_name": "suhemparack", - "name": "Suhem Parack", - "id": 857699969263964200, - "id_str": "857699969263964161", - "indices": [ - 3, - 15 - ] - }], - "symbols": [] - }, - "twitter_lang": "en", - "retweetCount": 19, - "gnip": { - "matching_rules": [{ - "tag": null - }], - "urls": [{ - "url": "https://t.co/l5J8wq748G", - "expanded_url": "https://dev.to/twitterdev/building-an-alexa-skill-for-twitter-using-alexa-presentation-language-1aj0", - "expanded_status": 200, - "expanded_url_title": null, - "expanded_url_description": null - }] - }, - "twitter_filter_level": "low" -} -``` - -Quote Tweet activity - -``` - { - "id": "tag:search.x.com,2005:1328399838128467969", - "objectType": "activity", - "verb": "post", - "postedTime": "2020-11-16T18:09:36.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/XDevelopers/statuses/1328399838128467969", - "body": "As planned, the Labs v2 endpoints referenced below have now been retired. Please let us know in the forums if you h… https://t.co/ahQvTYaOcZ", - "long_object": { - "body": "As planned, the Labs v2 endpoints referenced below have now been retired. Please let us know in the forums if you have questions or need help with the X API v2! https://t.co/JaxttUMmjX", - "display_text_range": [ - 0, - 166 - ], - "twitter_entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/JaxttUMmjX", - "expanded_url": "https://x.com/XDevelopers/status/1327011423252144128", - "display_url": "x.com/XDevelopers/sta…", - "indices": [ - 167, - 190 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "display_text_range": [ - 0, - 140 - ], - "actor": { - "objectType": "person", - "id": "id:twitter.com:2244994945", - "link": "http://www.x.com/XDevelopers", - "displayName": "X Dev", - "postedTime": "2013-12-14T04:35:55.036Z", - "image": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "summary": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "friendsCount": 2038, - "followersCount": 512292, - "listedCount": 1666, - "statusesCount": 3634, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "XDevelopers", - "languages": [], - "links": [{ - "href": "https://developer.x.com/en/community", - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "127.0.0.1" - }, - "favoritesCount": 2147 - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1328399838128467969", - "summary": "As planned, the Labs v2 endpoints referenced below have now been retired. Please let us know in the forums if you h… https://t.co/ahQvTYaOcZ", - "link": "http://x.com/XDevelopers/statuses/1328399838128467969", - "postedTime": "2020-11-16T18:09:36.000Z" - }, - "favoritesCount": 29, - "twitter_entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/ahQvTYaOcZ", - "expanded_url": "https://x.com/i/web/status/1328399838128467969", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "twitter_lang": "en", - "retweetCount": 7, - "gnip": { - "matching_rules": [{ - "tag": null - }], - "urls": [{ - "url": "https://t.co/r6z6CI7kEy", - "expanded_url": "https://devcommunity.x.com/t/retiring-labs-v2-recent-search-and-hide-replies/145795", - "expanded_status": 200, - "expanded_url_title": "Retiring Labs v2 recent search and hide replies", - "expanded_url_description": "As we said in our Early Access and hide replies announcements, the following X Developer Labs v2 endpoints will be retired on November 16th. Labs v2 recent search Labs v2 hide replies If called, these endpoints will respond with an HTTP 410 status and return no data. Based on your feedback from Labs, we incorporated corresponding functionality into the X API v2. The relevant documentation can be found using the links below. Click here to enroll in v2 access if you haven’t already..." - }] - }, - "twitter_filter_level": "low", - "twitter_quoted_status": { - "id": "tag:search.x.com,2005:1327011423252144128", - "objectType": "activity", - "verb": "post", - "postedTime": "2020-11-12T22:12:32.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/XDevelopers/statuses/1327011423252144128", - "body": "👋 Friendly reminder that X Developer Labs v2 hide replies and recent search will be retired next Monday, Nove… https://t.co/EEWN2Q9aXh", - "long_object": { - "body": "👋 Friendly reminder that X Developer Labs v2 hide replies and recent search will be retired next Monday, November 16! We encourage you to migrate to the new hide replies and recent search endpoints now available in the v2 #XAPI. Details: https://t.co/r6z6CI7kEy", - "display_text_range": [ - 0, - 273 - ], - "twitter_entities": { - "hashtags": [{ - "text": "API", - "indices": [ - 228, - 239 - ] - }], - "urls": [{ - "url": "https://t.co/r6z6CI7kEy", - "expanded_url": "https://devcommunity.x.com/t/retiring-labs-v2-recent-search-and-hide-replies/145795", - "display_url": "devcommunity.com/t/retiring-lab…", - "indices": [ - 250, - 273 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "actor": { - "objectType": "person", - "id": "id:twitter.com:2244994945", - "link": "http://www.x.com/XDevelopers", - "displayName": "X Dev", - "postedTime": "2013-12-14T04:35:55.036Z", - "image": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "summary": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "friendsCount": 2038, - "followersCount": 512292, - "listedCount": 1666, - "statusesCount": 3634, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "XDevelopers", - "languages": [], - "links": [{ - "href": "https://developer.x.com/en/community", - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "127.0.0.1" - }, - "favoritesCount": 2147 - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1327011423252144128", - "summary": "👋 Friendly reminder that X Developer Labs v2 hide replies and recent search will be retired next Monday, Nove… https://t.co/EEWN2Q9aXh", - "link": "http://x.com/XDevelopers/statuses/1327011423252144128", - "postedTime": "2020-11-12T22:12:32.000Z" - }, - "favoritesCount": 33, - "twitter_entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/EEWN2Q9aXh", - "expanded_url": "https://x.com/i/web/status/1327011423252144128", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "twitter_lang": "en", - "twitter_filter_level": "low" - } - } - ``` - -Retweetd Quote Tweet activity - -``` -{ - "id": "tag:search.x.com,2005:1225470895902412800", - "objectType": "activity", - "verb": "share", - "postedTime": "2020-02-06T17:26:44.000Z", - "generator": { - "displayName": "X for iPhone", - "link": "http://x.com/download/iphone" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/XDevelopers/statuses/1225470895902412800", - "body": "RT @AureliaSpecker: 📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses…", - "actor": { - "objectType": "person", - "id": "id:twitter.com:2244994945", - "link": "http://www.x.com/XDevelopers", - "displayName": "X Dev", - "postedTime": "2013-12-14T04:35:55.036Z", - "image": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "summary": "The voice of the #XDevelopers team and your official source for updates, news, and events, related to the #XAPI.", - "friendsCount": 2038, - "followersCount": 512292, - "listedCount": 1666, - "statusesCount": 3634, - "twitterTimeZone": null, - "verified": true, - "utcOffset": null, - "preferredUsername": "XDevelopers", - "languages": [], - "links": [{ - "href": "https://developer.x.com/en/community", - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "127.0.0.1" - }, - "favoritesCount": 2147 - }, - "object": { - "id": "tag:search.x.com,2005:1224709550214873090", - "objectType": "activity", - "verb": "post", - "postedTime": "2020-02-04T15:01:25.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/AureliaSpecker/statuses/1224709550214873090", - "body": "📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that u… https://t.co/cAepHunkFp", - "long_object": { - "body": "📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses X's new search endpoint 🚇 https://t.co/87XIPZmZBJ\n\n#DEVcommunity #Pythontutorial @XDevelopers @API https://t.co/dXrJYvn3hY", - "display_text_range": [ - 0, - 229 - ], - "twitter_entities": { - "hashtags": [{ - "text": "DEVcommunity", - "indices": [ - 176, - 189 - ] - }, - { - "text": "Pythontutorial", - "indices": [ - 190, - 205 - ] - } - ], - "urls": [{ - "url": "https://t.co/87XIPZmZBJ", - "expanded_url": "https://bit.ly/2OrnrCC", - "display_url": "bit.ly/2OrnrCC", - "indices": [ - 151, - 174 - ] - }, - { - "url": "https://t.co/dXrJYvn3hY", - "expanded_url": "https://x.com/AureliaSpecker/status/1195000047089389573", - "display_url": "x.com/AureliaSpecker…", - "indices": [ - 230, - 253 - ] - } - ], - "user_mentions": [{ - "screen_name": "XDevelopers", - "name": "X Dev", - "id": 2244994945, - "id_str": "2244994945", - "indices": [ - 206, - 217 - ] - }, - { - "screen_name": "API", - "name": "X API", - "id": 6253282, - "id_str": "6253282", - "indices": [ - 218, - 229 - ] - } - ], - "symbols": [] - } - }, - "display_text_range": [ - 0, - 140 - ], - "actor": { - "objectType": "person", - "id": "id:twitter.com:1102321381", - "link": "http://www.x.com/AureliaSpecker", - "displayName": "Aurelia Specker", - "postedTime": "2013-01-18T23:45:43.000Z", - "image": "https://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", - "summary": "devrel @TwitterUK • Swiss in London • mother of houseplants • personal hairdresser to @_dormrod", - "friendsCount": 1331, - "followersCount": 1032, - "listedCount": 26, - "statusesCount": 854, - "twitterTimeZone": null, - "verified": false, - "utcOffset": null, - "preferredUsername": "AureliaSpecker", - "languages": [], - "links": [{ - "href": null, - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "London, UK" - }, - "favoritesCount": 4979 - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1224709550214873090", - "summary": "📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that u… https://t.co/cAepHunkFp", - "link": "http://x.com/AureliaSpecker/statuses/1224709550214873090", - "postedTime": "2020-02-04T15:01:25.000Z" - }, - "favoritesCount": 43, - "twitter_entities": { - "hashtags": [], - "urls": [{ - "url": "https://t.co/cAepHunkFp", - "expanded_url": "https://x.com/i/web/status/1224709550214873090", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "twitter_lang": "en", - "twitter_filter_level": "low" - }, - "favoritesCount": 0, - "twitter_entities": { - "hashtags": [], - "urls": [], - "user_mentions": [{ - "screen_name": "AureliaSpecker", - "name": "Aurelia Specker", - "id": 1102321381, - "id_str": "1102321381", - "indices": [ - 3, - 18 - ] - }], - "symbols": [] - }, - "twitter_lang": "en", - "retweetCount": 12, - "gnip": { - "matching_rules": [{ - "tag": null - }], - "urls": [{ - "url": "https://t.co/87XIPZmZBJ", - "expanded_url": "https://dev.to/XDevelopers/migrate-to-twitter-s-newly-released-labs-recent-search-endpoint-3npe", - "expanded_status": 200, - "expanded_url_title": null, - "expanded_url_description": null - }, - { - "url": "https://t.co/sOjXW4YhbN", - "expanded_url": "https://dev.to/XDevelopers/using-the-twitter-api-to-make-your-commute-easier-3od0", - "expanded_status": 200, - "expanded_url_title": null, - "expanded_url_description": null - } - ] - }, - "twitter_filter_level": "low", - "twitter_quoted_status": { - "id": "tag:search.x.com,2005:1195000047089389573", - "objectType": "activity", - "verb": "post", - "postedTime": "2019-11-14T15:26:27.000Z", - "generator": { - "displayName": "X Web App", - "link": "https://mobile.x.com" - }, - "provider": { - "objectType": "service", - "displayName": "X", - "link": "http://www.x.com" - }, - "link": "http://x.com/AureliaSpecker/statuses/1195000047089389573", - "body": "I wrote a tutorial on how to get bespoke commute information using the X API🚇\n\n#DEVcommunity #Pythontutorial… https://t.co/pL0qJ4vhtE", - "long_object": { - "body": "I wrote a tutorial on how to get bespoke commute information using the X API🚇\n\n#DEVcommunity #Pythontutorial \n\nCheck it out here 👇\nhttps://t.co/sOjXW4YhbN", - "display_text_range": [ - 0, - 160 - ], - "twitter_entities": { - "hashtags": [{ - "text": "DEVcommunity", - "indices": [ - 85, - 98 - ] - }, - { - "text": "Pythontutorial", - "indices": [ - 99, - 114 - ] - } - ], - "urls": [{ - "url": "https://t.co/sOjXW4YhbN", - "expanded_url": "https://dev.to/XDevelopers/using-the-twitter-api-to-make-your-commute-easier-3od0", - "display_url": "dev.to/twitterdev/usi…", - "indices": [ - 137, - 160 - ] - }], - "user_mentions": [], - "symbols": [] - } - }, - "actor": { - "objectType": "person", - "id": "id:twitter.com:1102321381", - "link": "http://www.x.com/AureliaSpecker", - "displayName": "Aurelia Specker", - "postedTime": "2013-01-18T23:45:43.000Z", - "image": "https://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", - "summary": "devrel @TwitterUK • Swiss in London • mother of houseplants • personal hairdresser to @_dormrod", - "friendsCount": 1331, - "followersCount": 1032, - "listedCount": 26, - "statusesCount": 854, - "twitterTimeZone": null, - "verified": false, - "utcOffset": null, - "preferredUsername": "AureliaSpecker", - "languages": [], - "links": [{ - "href": null, - "rel": "me" - }], - "location": { - "objectType": "place", - "displayName": "London, UK" - }, - "favoritesCount": 4979 - }, - "object": { - "objectType": "note", - "id": "object:search.x.com,2005:1195000047089389573", - "summary": "I wrote a tutorial on how to get bespoke commute information using the X API🚇\n\n#DEVcommunity #Pythontutorial… https://t.co/pL0qJ4vhtE", - "link": "http://x.com/AureliaSpecker/statuses/1195000047089389573", - "postedTime": "2019-11-14T15:26:27.000Z" - }, - "favoritesCount": 123, - "twitter_entities": { - "hashtags": [{ - "text": "DEVcommunity", - "indices": [ - 85, - 98 - ] - }, - { - "text": "Pythontutorial", - "indices": [ - 99, - 114 - ] - } - ], - "urls": [{ - "url": "https://t.co/pL0qJ4vhtE", - "expanded_url": "https://x.com/i/web/status/1195000047089389573", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 116, - 139 - ] - }], - "user_mentions": [], - "symbols": [] - }, - "twitter_lang": "en", - "twitter_filter_level": "low" - } -} -``` -## Tweet metadata timeline -Jump to on this page - -[Introduction](#intro) - -[Key concepts](#key_concepts) - -[X timeline](#twitter_timeline) - -[Filtering tips](#filtering_tips) - -[Next steps](#next) - -### Introduction** - -At its core, X is a public, real-time, and global communication network. Since 2006, X's evolution has been driven by both user use-patterns and conventions and new product features and enhancements. If you are using X data for historical research, understanding the timeline of this evolution is important for surfacing Posts of interest from the data archive. - -X was launched as a simple SMS mobile app, and has grown into a comprehensive communication platform. A platform with a complete set of APIs. APIs have always been a pillar of the X network. The [first API hit the streets soon after X was launched](https://blog.x.com/2006/introducing-the-twitter-api). When geo-tagging Posts was first introduced in 2009, it was made available through a [Geo API](https://blog.x.com/2009/think-globally-tweet-locally) (and later the ability to ‘geo-tag’ a Post was integrated into the X.com user-interface). Today, X's APIs drive the two-way communication network that has become the source of breaking news and sharing information. The opportunities to build on top of this global, real-time communication channel are endless. - -X makes available two historical APIs that provide access to every publicly available Post: Historical PowerTrack and the [Full-Archive Search API](https://developer.x.com/en/docs/x-api/v1/tweets/search/overview). Both APIs provide a set of _operators_ used to query and collect Posts of interest. These operators match on a variety of attributes associated with every Post, hundreds of attributes such as the Post's text content, the author’s account name, and links shared in the Post. Posts and their attributes are encoded in JSON, a common text-based data-interchange format. So as new features were introduced, new JSON attributes appeared, and typically new API operators were introduced to match on those attributes. If your use-case includes a need to _listen_ to what the world has said on X, the better you understand when operators started having JSON metadata to match on, the more effective your historical PowerTrack filters can be. - -Next, we will introduce some key concepts that set the stage for understanding how updates in Post metadata affect finding your data signal of interest. - -### Key concepts** - -#### From user-conventions to X _first-class objects_ - -X users organically introduced new, and now fundamental, communication patterns to the X network. A seminal example is the hashtag, now nearly universally used across all social networks. Hashtags were introduced as a way to organize conversations and topics. On a network with hundreds of millions messages a day, tools to find Posts of interest are key, and hashtags have become a fundamental method. Soon after the use of hashtags grew, they received official status and support from X. As hashtags became a _‘first-class’ object_, this meant many things. It meant hashtags became clickable/searchable in the X.com user interface. It also meant hashtags became a member of the X _entities_ family, along with @mentions, attached media, stock symbols, and shared links. These entities are conveniently encoded in a pre-parsed JSON array, making it easier for developers to process, scan, and store them. - -Retweets are another example of user-driven conventions becoming official objects. Retweeting emerged as a way of ‘forwarding’ content to others. It started as a manual process of copying/pasting a Post and prepending it with a “RT @” pattern. This process was eventually automated via a new Retweet button, complete with new JSON metadata. The ‘official’ Retweet was born. Other examples include ‘mentions’, sharing of media and web links, and sharing a location with your Post. Each of these use-patterns resulted in new [x.com](https://x.com/) user-interface features, new supporting JSON, and thus new ways to match on Posts. All of these fundamental Post attributes have resulted in PowerTrack Operators used to match on them. - -#### Post metadata, mutability, updates, and currency - -While Post messages can be up to a fixed number of characters long, the JSON description of a Post consists of over 100 attributes. Attributes such as who posted, at what time, whether it’s an original Post or a Retweet, and an array of first-class objects such as hashtags, mentions, and shared links. For the account that posted, there is a User (or Actor) object with a variety of attributes that provide the user’s Profile and other account metadata. Profiles include a short biographical description, a home location (freeform text), preferred language, and an optional web site link. - -Some account metadata never change (e.g. numeric user ID and created date), some change slowly over time, while other attributes change more frequently. People change jobs and move. Companies updates their information. When you are collecting historical Posts, it is important to understand how some metadata is _as it was when Posted_, and other metadata is _as it is when the query is submitted_.  - -With all historical APIs, the user's profile description, display name, and profile 'home' attributes are updated to the values at the time of query. - -#### “Native” media - -X.com and X mobile apps support adding photos and videos to Post by clicking a button and browsing your photo galleries. Now that they are integrated as first-class actions, videos and photos shared this way are referred to as ‘native’ media. - -Many querying Operators work with these ‘native’ resources, including `has:videos`, `has:images`, and `has:media`. These will match only on media content that was shared via X features. To match on other media hosted off of the X platform, you’ll want to use Operators that match on URL metadata. - -So, before we dig into the Historical PowerTrack and Full-Archive Search product details, let’s take a tour of how X, as a product and platform, evolved over time. - -**X timeline** - -Below you will find a select _timeline_ of X. Most of these X updates in some way fundamentally affected either user behavior, Post JSON contents, query Operators, or all three. Looking at X as a API platform, the following events in some way affected the JSON payloads that are used to encode Posts. In turn, those JSON details affect how X historical API match on them. - -Note that this timeline list is generally precise and not exhaustive. - -#### 2006 - -* October - * @replies becomes a convention. - * $cashtags first emerge, but using for stock ticker mentions does not become common until early 2009. $Cashtags became a clickable/searchable link in June 2012. -* November - Favorites introduced. - -#### 2007 - -* January - @replies become a first-class object with a UI reply button with `in_reply_to` metadata. -* April - Retweets become a convention. -* August - #hashtags emerge as a primary tool for searching and organizing Posts. - -#### 2009 - -* February - $cashtags become a common convention for discussing stock ticker symbols. -* May - Retweet ‘beta’ is introduced with “Via @” prepended to Post body. -* June - Verified accounts introduced. -* August - Retweets a first-class object with “RT @” pattern and new `retweet_status` metadata. -* October - List feature launched. -* November - [Post Geotagging API is launched](https://blog.x.com/2009/think-globally-tweet-locally), providing the first method for users to share location via third-party apps. - -#### 2010 - -* June - X Places introduced for geo-tagging Posts. -* August - Post button for websites is launched. Made sharing links easier. - -#### 2011 - -* May - Follow button introduced, making it easier to follow accounts associated with websites. -* August - Native photos introduced. - -#### 2012 - -* June - $Cashtags become a clickable/searchable link. - -#### 2014 - -* March - [Photo tagging and up to four photos supported](https://blog.x.com/2014/photos-just-got-more-social). _Extended_ X Entities metadata was introduced. -* April - Emojis are natively supported in X UI. Emojis were commonly used in Posts since at least 2008. - -#### 2015 - -* April - A change in X's ‘post’ user-interface design results in fewer Posts being geo-tagged. -* October - [X Polls introduced](https://blog.x.com/2015/introducing-twitter-polls). Polls originally supported two choices with a 24-hour voting period. In November, Polls started supporting four choices with voting periods from 5 minutes to seven days. Poll metadata made available (enriched native format only) in February 2017. - -#### 2016 - -* February - [Searchable GIFs natively hosted in Post compose](https://blog.x.com/2016/introducing-gif-search-on-twitter). -* May - [“Doing More with 140”](https://blog.x.com/express-even-more-in-140-characters) (dmw140) announced, stating plans for new ways of handling Replies and attached media with respect to a Post's 140-character message. -* June - [Native video support](https://blog.x.com/official/en_us/a/2016/new-ways-to-tap-into-video-on-twitter.html) -* June - Quoted Retweets generally available. -* June - [Stickers introduced for adding to photos](https://blog.x.com/2016/introducing-stickers-on-twitter). -* September - [‘Native attachments’ introduced](https://x.com/X/status/777915304261193728) with trailing URL not counted towards 140 characters (“dmw140, part 1”). - -#### 2017 - -* February - X Poll metadata included in Post metadata (enriched native format only). -* April - [‘Simplified Replies’](https://blog.x.com/2017/now-on-twitter-140-characters-for-your-replies) introduced with replied-to-accounts not counted towards 140 characters (“dmw140, part 2”). - -2018 - -* May - [GDPR updates](https://devcommunity.x.com/t/upcoming-changes-to-the-developer-platform/104603) user.time\_zone set to null, user.utc\_offset set to null, user.profile\_background\_image_url set to default value -* June - Updating [quoteTweet formatting changes](https://devcommunity.x.com/t/updating-how-urls-are-rendered-in-the-quote-tweet-payload/105473) - -2022 - -* September 29 - The ability to edit Posts is rolled out to a small test group. Edited Post metadata are added to the Post object where relevant. This includes edit_history and edit_controls objects. These metadata will not be returned for Posts that were created before editable functionality was added. No associated Operators for these metadata. To learn more about how Post edits work, see the [Edit Posts fundamentals](/x-api/fundamentals/edit-posts) - -**Filtering tips** - -Being familiar with the X timeline of when and how new features were added can help you create more effective queries. Here, a query means a _filter_ or _rule_ that is applied by the X historical APIs to the Post archive, using PowerTrack Operators to match on Post JSON. An example is the `lang:` Operator, which is used to match Posts in a specified language. X provides a language classification service (supporting over 50 languages), and X APIs provide this metadata in the JSON that is generated for every Post. So, if a Post is written in Spanish the “lang” JSON attribute is set to “es”. So, if you build a filter with the `lang:es` clause, it will only match on Post messages classified as Spanish. - -The timeline information can also help better interpret the Post data received. Say you were researching the sharing of content about the 2008 and 2012 Summer Olympics. If you applied only the `is:retweet` Operator to match on Retweets, no data would match in 2008. However, for 2012 there would likely be millions of Retweets. From this you potentially could erroneously conclude that in 2008 Retweets were not a user convention, or that simply no one Retweeted about those Olympics. Since Retweets became a first-class object in 2009, you need to add a `”RT @”` rule clause to help identify them in 2008. - -Both Retweets and Post language classifying are examples of Post attributes with a long history and many product details. Below we will discuss more details of these and other attribute classes important to matching on and understanding X Data. - -#### Recognizing false negatives - -When it comes to writing filters, one important takeaway is that the metadata Operators match on all have “born on” dates. If you build a filter with an Operator that acts on metadata introduced after the Post was posted, you’ll have a false negative. For example, say you are interested in all Posts that mention ‘snow’ and share a video. If you build a rule with the `has:videos` Operator, which matches on Posts with _native_ videos, that clause will not match any Posts before 2015. - -However, sharing of videos has been common on X long before 2015. Before then users shared links to videos hosted elsewhere, but in 2015, X built new ‘sharing video’ features directly into the platform. For finding these earlier Posts of interest, you would include a rule clause such as `url:”youtube.com”`. - -Note, with the Search APIs, there are some examples of metadata being ‘backfilled’ as its index was rebuilt. One good example are $cashtags, which became widely used to discuss stock symbols in 2009. After the $cashtag operator was introduced in 2015, the Search index was rebuilt, and in the process the symbol entity was extracted from all Post bodies, including early 2006 when `$` was used mainly for slang; “I hope it $now$ $oon!”. - -#### Identifying and filtering on Post attributes important to your use-case - -Some metadata, such as X account numeric IDs, have existed since day one (and are an example of account metadata that never changes). Other metadata was not introduced until well after X started in 2006. Examples of new metadata being introduced include Retweets metadata, Post locations, URL titles and descriptions, and ‘native’ media. Below are some of the most common types of Post attributes that have been fundamentally affected by these X platform updates. - -Filtering/matching behavior for these depends, in most cases, on which historical Post API is used. To help determine which product is the best fit for your research and use-case, the attribute details provided below include high-level product information. - -#### X Profiles - -Since at its core X is a global real-time communication channel, research with Post data commonly has an emphasis on who is communicating. Often it is helpful to know where a X user calls home. Often knowing that an account bio includes mentions of interests and hobbies can lead you to Post of interest. It is very common to want to listen for Posts from accounts of interest. Profile attributes are key to all of these use-cases. - -Every account on X has a Profile that includes metadata such as X @handle, display name, a short bio, home location (freeform text entered by a user), number of followers and many others. Some attributes never change, such as numeric user ID and when the account was created. Others usually change day-to-day, week-to-week, or month-to-month, such as number of Posts posted and number of accounts followed and followers. Other account attributes can also change at any time, but tend to change less frequently: display name, home location, and bio. - -The JSON payload for every Post includes _account profile_ metadata for the Post's author. If it is a Retweet, it also includes profile metadata for the account that posted the original Post. - -The mutability of a Post's profile metadata depends entirely on the historical product used. The Search APIs serve up historical Posts with the profile settings _as it is at the time of retrieval_. For Historical PowerTrack, the profile is _as it was at the time the Post was posted_, except for data before 2011. For Posts older than 2011, the profile metadata reflects the profile as it was in September 2011. - -#### Original Post and Retweets - -Retweets are another example of user-driven conventions becoming official objects. Retweeting emerged as a way of ‘forwarding’ content to others. It started as a manual process of copying/pasting a Post and prepending it with a “RT @” pattern. This process was eventually automated via a new Retweet button, complete with new JSON metadata. The ‘official’ Retweet was born and the action of retweeting became a first-class Post event. Along with the new Retweet button, new metadata was introduced such as the complete payload of the original Post. - -Whether a Post is original or shared is a common filtering ‘switch.’ In some cases, only original content is needed. In other cases, Post engagement is of primary importance so Retweets are key. The PowerTrack `is:retweet` Operator enables users to either include or exclude Retweets. If pulling data from before August 2009, users need to have _two_ strategies for Retweet matching (or not matching). Before August 2009, the Post message itself needs to be checked, using exact phrase matching, for matches on the “@RT ” pattern. For periods after August 2009, the `is:retweet` Operator is available. - -#### Post language classifications - -The language a Post is written in is a common interest. Post language can help infer a Post's location and often only a specific language is needed for analysis or display. (X profiles also have a preferred language setting.) - -For filtering on a Post's language classification, X's historical products ([Search API](https://developer.x.com/en/docs/x-api/v1/tweets/search/overview/enterprise) and Historical PowerTrack) are quite different. When the Search archive was built, all posts were backfilled with the X language classification. Therefore the `lang:` Operator is available for the entire post archive. With Historical PowerTrack, X's language classification metadata is available in the archive beginning on March 26, 2013.  - -#### Geo-referencing Posts - -Being able to tell where a Post was posted (i.e., geo-referencing it) is important to many use-cases. There are three primary methods for geo-referencing Posts: - -* Geographical references in a Post message -* Posts geo-tagged by the user. -* Account profile ‘home’ location set by a user - -##### Geographical references in a Post message - -Matching on geographic references in the Post message, while often the most challenging method since it depends on local knowledge, is an option for the entire Post archive. Here is an example geo-referenced match from 2006 for the San Francisco area based on a ‘golden gate’ filter: - -https://x.com/biz/statuses/28311 - -##### Posts geo-tagged by the user - -In November 2009 X introduced its Post Geotagging API that enabled Posts to be geo-tagged with an exact location. In June 2010 X introduced X Places that represent a geographic area on the venue, neighborhood, or town scale. Approximately 1-2% of Posts are geo-tagged using either method. - -The available geo-tagging history is dependent on the Historical API you are using. With the Search APIs the ability to start matching on Posts with some Geo Operators started in March 2010, and with others on February 2015. If you are using Historical PowerTrack, geo-referencing starts on September 1, 2011. When the Historical PowerTrack archive was built, all geo-tagging before this date was not included. - -##### Account profile ‘home’ location set by a user - -All X users have the opportunity to set their Profile Location, indicating their home location. Millions of X users provide this information, and it significantly increases the amount of geodata in the X Firehose. This location metadata is a non-normalized, user-generated, free-form string. Approximately 30% of accounts have Profile Geo metadata that can be resolved to the country level. - -As with Post geo, the methods to match and the time periods available depends on the Historical API you are using. Historical PowerTrack enables users to attempt their own custom matching on these free-form strings. To help make that process easier, X also provides a [Profile Geo Enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) that performs the geocoding where possible, providing normalized metadata and corresponding Operators. Profile Geo Operators are available in both Historical PowerTrack and the Search APIs. With Historical PowerTrack, these Profile Geo metadata is available starting in June 2014. With the Search APIs, this metadata is available starting in February 2015. - -#### Shared links and media - -Sharing web page links, photos and videos have always been a fundamental X use-case. Early in its history, all of these actions involved including a URL link in the Post message itself. In 2011 X integrated sharing photos directly into its user-interface. In 2016, native videos were added. - -Given this history, there are a variety of filtering Operators used for matching on this content. There are a set of Operators that match on whether Posts have shared links, photos, and videos. Also, since most URLs shared on X are shortened to use up fewer of a Post's characters (e.g. generated by a service such as bitly or tinyurl), X provides data enrichments that generate a complete, expanded URL that can be matched on. For example, if you wanted to match on Posts that included links discussing X and Early-warning systems, a filter that references ‘severe weather communication’ would match a Post containing this [http://bit.ly/1XV1tG4](http://bit.ly/1XV1tG4) URL. - -In March 2012, the [expanded URL enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#expanded-and-enhanced-urls) was introduced. Before this time, the Post payloads included only the URL as provided by the user. So, if the user included a shortened URL it can be challenging to match on (expanded) URLs of interest. With both Historical PowerTrack and the Search APIs, these metadata are available starting in March 2012. - -In July 2016, the enhanced URL enrichment was introduced. This enhanced version provides a web site’s HTML title and description in the Post payload, along with Operators for matching on those. With Historical PowerTrack, these metadata become available in July 2016. With the Search APIs, these metadata begin emerging in December 2014. - -In September 2016 X introduced ‘native attachments’ where a trailing shared link is not counted against the 140 Post character limit. Both URL enrichments still apply to these shared links. - -For other URL product-specific details on URL filtering, see the corresponding articles for more information. - diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/data-enrichments.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/data-enrichments.mdx deleted file mode 100644 index 2f507d2ba..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/data-enrichments.mdx +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: "Data enrichments: Enterprise" -keywords: ["data enrichments", "enterprise enrichments", "GNIP enrichments", "data enrichment", "enriched data", "enterprise data enrichment"] ---- - - -## Introduction - -`Enterprise` - -Enterprise enrichments are additive metadata included in the response payload of some of the data APIs. They are available in paid subscription plans only. - -The table below offers a brief description of each enrichment: - -| Enrichment: | Description: | -| :--- | :--- | -| Expanded and Enhanced URLs | Automatically expands shortened URLs (e.g., bitly) that are included in the body of a Post and provides HTML Title and Description metadata from the destination page. | -| Matching rules object | Indicates which rule or rules matched the Posts received. The object returns rule tag and rule ID in the response object. | -| Poll metadata | Notes the presence of the poll in a Post, includes the list of poll choices, and includes both the poll duration and expiration time. | -| Profile geo | Derived user profile location data including the \[longitude, latitude\] coordinates (where possible) and related place metadata. | - - -### Expanded and Enhanced URLs - -The Expanded and Enhanced URL enrichment automatically expands shortened URLs that are included in the body of a Post, and includes the resulting URL as metadata within the payload. In addition, this enrichment also provides HTML page metadata from the `title` and `description` of the destination page. - -**Important Details:** - -* To resolve a shortened link, our system sends HTTP HEAD requests to the URL provided and follows any redirects until it arrives at the final URL. This final URL (NOT the content of the page itself) is then included in the response payload. - -* The URL enrichment does add between 5-10 seconds latency to realtime streams -* For requests made to the Full Archive Search API, expanded URL enrichment data is only available for Posts 13 months old or newer. - -* The URL enrichment is not available for Post links (including quote Tweets), Moments links, and profile links that are included within a Post.  -   - -#### Post payload - -The Expanded and Enhanced URL enrichment can be found within the `entities` object of the Post payload - specifically in the `entitites.urls.unwound` object. It provides the following fields of metadata: - -* Expanded URL - `unwound.url` -* Expanded HTTP Status - `unwound.status` -* Expanded URL HTML title - 300 character limit - `unwound.title` -* Expanded URL HTML description - 1000 character limit - `unwound.description` - - -**This is an example of an [entities object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-entities) with the URL enrichment:** -``` -"entities": { - "hashtags": [ - - ], - "urls": [ - { - "url": "https:\/\/t.co\/HkTkwFq8UT", - "expanded_url": "http:\/\/bit.ly\/2wYTb9y", - "display_url": "bit.ly\/2wYTb9y", - "unwound": { - "url": "https:\/\/www.forbes.com\/sites\/laurencebradford\/2016\/12\/08\/11-websites-to-learn-to-code-for-free-in-2017\/", - "status": 200, - "title": "11 Websites To Learn To Code For Free In 2017", - "description": "It\u2019s totally possible to learn to code for free...but what are the best resources to achieve that? Here are 11 websites where you can get started." - }, - "indices": [ - 10, - 33 - ] - } - ], - "user_mentions": [ - - ], - "symbols": [ - - ] - }, - ``` - - - -**This is an example of an entities object containing a Post link that is not enriched: -** - -``` -"entities": { - "urls": [{ - "url": "https://t.co/SywNbZdDmb", - "expanded_url": "https://x.com/XDevelopers/status/1050118621198921728", - "display_url": "x.com/XDevelopers/s…", - "indices": [ - 142, - 165 - ] - } - ] -} -``` - -#### Filtering operators - -The following operators will filter and provide a tokenized match on the related fields of URL metadata: - -**url:** - -* Example: “url:tennis” -* Tokenized match on any Expanded URL that includes the word tennis -* Could also be used as a filter to include or exclude links from a specific website using something like “url:npr.org” - -**url_title:** - -* Example: “url_title:tennis” -* Tokenized match on any Expanded URL HTML title that includes the word tennis -* Matches on the HTML title data included in the payload, which is limited to 300 characters. - -**url_description:** - -* Example: “url_description:tennis” -* Tokenized match on any Expanded URL HTML description that includes the word tennis -* Matches on the HTML description included in the payload, which is limited to 1000 characters. -   - -#### HTTP Status Codes - -The expanded URL enrichment also provides the HTTP status code for the final URL we are attempting to unwind. In normal cases, this will be a 200 value. Other 400-series values indicate problems with resolving the URL. - -Various status codes may be returned when attempting to unwind a URL. During the process of unwinding a URL, if we get a redirect, we will follow them indefinitely until we either: - -* Hit a 200 series code (success) -* Hit a non-redirect series code (failures) -* Timeout because the final URL could not be resolved in a reasonable amount of time (returns a 408 - timeout) -* Hit an exception of some sort -   - -If an exception is hit, we use the following mapping between reasons and status codes returned: - -| Reason | Status Code Returned | -| :--- | :--- | -| SSL Exceptions | 403 (Forbidden) | -| Unwinding not allowed by URL | 405 | -| Socket Timeout | 408 (Timeout) | -| Unknown Host Exception | 404 (Not Found) | -| Unsupported Operation | 404 (Not Found) | -| Connect Exception | 404 (Not Found) | -| Illegal Argument | 400 (Bad Request) | -| Everything else | 400 (Bad Request) | - - -### Matching rules - -The matching rules enrichment is an object of metadata that indicates which rule or rules matched the Posts received. This is most commonly used with the PowerTrack stream. - -Matching will be done via exact match on the terms contained in a rule, scanning the content of the activity with and without punctuation. Matching is not case sensitive. When the content is found to contain all terms defined in the rule, there will be a root-level a matching_rules object indicating the rule(s) that led to the match. - -**PowerTrack** - -Posts delivered through PowerTrack (realtime, Replay, and Historical) will contain the matching_rules object as follows: - -``` -"matching_rules": [{ - "tag": null, - "id": 907728589029646336, - "id_str": "907728589029646336" - }] - ``` - - - -In PowerTrack, the `matching_rules` object reflects _all_ rules that matched the given result. In other words, if more than one rule matches a specific Post, it will only be delivered once, but the `matching_rules` element will contain all the rules that matched. - - -### Poll metadata - -Poll metadata is a free enrichment available across all products (Realtime & Historical APIs) in enriched native format payloads. The metadata notes the presence of the poll in a Post, includes the list of poll choices, and includes both the poll duration and expiration time. This enrichment makes it easy to acknowledge the presence of a poll and enables proper rendering of a poll Post for display. - -##### Important Details: - -* Available across all enterprise APIs (PowerTrack, Replay, Search, Historical PowerTrack) - * _Note:_ For Replay and Historical PowerTrack, this metadata was first made available on 02/22/17. -* Does not include vote information or poll results -* Does not currently have filter/operator support -* Available in **enriched native format** only - * Enriched native format is a user-controlled setting that can be changed at any time through the Console: _Select a Product (PowerTrack, Replay, Search) > Settings tab > Output Format (Leave data in its original format)_ - -#### Post Payload - -Poll Post will contain the following metadata in the “entities.polls” object in the payload: - -* An “options” array with up to four options that include the position (1-4) and option text -* Poll expiration date -* Poll duration - -See the sample payload below for further reference. - -#### Sample Payload - -Below is a snippet of the enriched native format payload highlighting the added poll metadata: -```json -"entities":{ - "hashtags":[], - "urls":[], - "user_mentions":[], - "symbols":[], - "polls":[ - { - "options":[ - { - "position":1, - "text":"The better answer" - }, - { - "position":2, - "text":"The best answer" - } - ], - "end_datetime":"Sat Feb 04 15:33:11 +0000 2017", - "duration_minutes":1440 - } - ] - }, -``` - -### Profile Geo - -#### Introduction - -Many X user profiles include public location information provided by the user. This data is returned as a normal string in user.location (see [User object data dictionary](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object)). The Profile Geo Enrichment adds structured geodata relevant to the user.location value by geocoding and normalizing location strings where possible. Both latitude/longitude coordinates and related place metadata are added to user.derived.locations _only_ when included as part of the Post payload in enterprise API products. This data is available when using [the enriched native format](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) and can be filtered with a combination of [PowerTrack rules](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#enterprise-operators). - -**Note:** Some of the supporting geodata used to create the Profile Geo enrichment comes from GeoNames.org and is used by X under the [Creative Commons Attribution 3.0 License](https://creativecommons.org/licenses/by/3.0/us/legalcode). - -Profile Geo data will be included in X's PowerTrack, Replay, Volume Stream, Search, and Historical PowerTrack APIs. - -#### Profile Geo Data - -| Enriched native field name | Example value | Description | -| :--- | :--- | :--- | -| user.derived.locations.country | United States | The country location for where the user that created the Post is from. | -| user.derived.locations.country_code | US | A two-letter ISO-3166 country code that corresponds to the country location for where the user that created the Post is from. | -| user.derived.locations.locality | Birmingham | The locality location (generally city) for where the user that created the Post is from. | -| user.derived.locations.region | Alabama | The region location (generally state/province) for where the user that created the Post is from. | -| user.derived.locations.sub_region | Jefferson County | The sub-region location (generally county) for where the user that created the Post is from. | -| user.derived.locations.full_name | Birmingham, Alabama, United States | The full name (excluding sub-region) for where the user that created the Post is from. | -| User.derived.locations.geo | See Below | An array that includes a lat/long value for a coordinate that corresponds to the lowers granularity location for where the user that created the Post is from. | - -The Historical PowerTrack, Search, and PowerTrack APIs supports filtering based on Profile Geo data. See the appropriate product documentation for more details on what operators are available for filtering on Profile Geo data. - -#### Sample Payload -``` -{ - "user": { - "derived": { - "locations": \[ - { - "country": "United States", - "country_code": "US", - "locality": "Birmingham", - "region": "Alabama", - "sub_region": "Jefferson County", - "full_name": "Birmingham, Alabama, United States", - "geo": { - "coordinates": \[ - -86.80249, - 33.52066 - \], - "type": "point" - } - } - \] - } - } -} -``` -#### Limitations - -* The Profile Geo enrichment attempts to determine the best choice for the geographic place described in the profile location string. The result may not be accurate in all cases due to factors such as multiple places with similar names or ambiguous names. -* If a value is not provided in a user’s profile location field (actor.location), we will not attempt to make a classification. -* Precision Level: If a Profile Geo Enrichment can only be determined with confidence at the country or region level, lower-level geographies such as subRegion and locality will be omitted from the payload. -* The Profile Geo enrichment provides lat/long coordinates (a single point) that corresponds to the Precision Level of the enrichment’s results. These coordinates represent the geographic center of the enrichment location results. For example, if the Precision Level is at the Country level, then those coordinates are set to the geographic center of that Country. -* The PowerTrack operators provided for address properties (locality/region/country/country code) are intentionally granular to allow for many rule combinations. When attempting to target a specific location that shares a name with another location, consider combining address rules. For instance, the following would avoid matches for “San Francisco, Philippines”: profile\_locality:”San Francisco” profile\_region:California When building rules that target individual Profile Geo fields, keep in mind that each increased level of granularity will limit the results you see. In some cases when attempting to look at data from a city, you may wish to only rely on a region rule where the region offers significant overlap with the city, e.g. the city of Zurich, Switzerland can be effectively targeted along with surrounding areas with profile_region:”Zurich”. -* Use with Native Geo Posts: The Profile Geo enrichment provides an alternative type of geography for a Post, different from the native geo value in the payload. These two types of geography can be combined together to capture all of the possible posts related to a given area (based on available geodata), though they are not conceptually equivalent. diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/decahose-api.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/decahose-api.mdx deleted file mode 100644 index 7a2690c5b..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/decahose-api.mdx +++ /dev/null @@ -1,395 +0,0 @@ ---- -title: Decahose API -keywords: ["Decahose", "10% stream", "decahose API", "enterprise decahose", "10% sampled stream", "enterprise streaming"] ---- - - -This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the ["Edit Posts" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets).  - -### Decahose stream - -[Enterprise](https://developer.x.com/en/products/x-api/enterprise) - -_This is an enterprise API available within our managed access levels only. To use this API, you must first set up an account with our enterprise sales team. [Learn more](https://developer.x.com/en/products/x-api/enterprise)_ - -The Decahose delivers a 10% random sample of the realtime X Firehose through a streaming connection. This is accomplished via a realtime sampling algorithm which randomly selects the data, while still allowing for the expected low-latency delivery of data as it is sent through the firehose by X. - -Below are some of the features available with Decahose: - -* **Expanded and enhanced URLs:** \- fully unwinds shortened URLs and provides additional metadata (page title and description) -* **Stream partitioning** \- 2 partitions, each containing 50% of volume of the Decahose stream -* **Enhanced reliability** \- geographic diversity of backend systems - -Note: This data is delivered in bulk, and does not support additional filtering (e.g. for keywords). - -`ENTERPRISE` -### Streaming likes - - -_This is an enterprise API available within our managed access levels only. To use this API, you must first set up an account with our enterprise sales team. [Learn more](https://developer.x.com/en/products/x-api/enterprise)_ - -Likes enable insight into who likes Posts and delivers accurate counts of likes. Gnip’s Firehose and Decahose can deliver public likes related to the Posts delivered via Gnip. This yields real-time public engagement and audience metrics associated with a Post. -  - -**Getting started with Likes** - -As you prepare to consume likes data, you should know that: - -* Likes are delivered via an independent, separate stream -* Likes are historically referred to as “Favorites”. The enriched native format payload maintains this nomenclature -* Streams include only public likes - * Public means that the liking user, Post creator and Post are all public on the platform -* Likes are very similar to Retweets and represent a public signal of engagement -* Payload elements include: - * Original Post object - * Actor object that created the original Post - * Actor object that performed the like action -* Only original content can be liked - * Retweets cannot be liked. A like of a Retweet is applied to the original Post - * Quoted Tweets _can_ be liked -* Like activities include applicable Gnip Enrichments (where purchased/applied) -* Supported Products / Features - * Likes streams support Backfill (where purchased/applied) - * There is no Replay support for likes streams - * There is no Search or Historical support for likes - * There are no immediate plans to add likes support to PowerTrack - -**Decahose** - -* For the 10% sample Posts delivered in the Decahose, stream includes 100% of the applicable public likes -* **Partitions:** 2 -* **URL Structure** - * https://gnip-stream.x.com/stream/sample10-likes/accounts/<accountName>/publishers/twitter/<streamLabel>.json?partition=1 - -**Native enriched format payload** - -```json -{ - "id":"43560406e0ad9f68374445f5f30c33fc", - "created_at":"Thu Dec 01 22:27:39 +0000 2016", - "timestamp_ms":1480631259353, - "favorited_status":{ - "created_at":"Thu Dec 01 22:27:16 +0000 2016", - "id":804451830033948672, - "id_str":"804451830033948672", - "text":"@kafammheppduman", - "source":"\u003ca href=\"http:\/\/x.com\/download\/android\" rel=\"nofollow\"\u003eX for Android\u003c\/a\u003e", - "truncated":false, - "in_reply_to_status_id":803694205163814912, - "in_reply_to_status_id_str":"803694205163814912", - "in_reply_to_user_id":2855759795, - "in_reply_to_user_id_str":"2855759795", - "in_reply_to_screen_name":"kafammheppduman", - "user":{ - "id":2855759795, - "id_str":"2855759795", - "name":"delirdim kanka", - "screen_name":"kafammheppduman", - "location":"sanane", - "url":"http:\/\/instagram.com\/kafammheppduman", - "description":"Manit @GalatasaraySk \ud83d\udc9e", - "translator_type":"none", - "protected":false, - "verified":false, - "followers_count":3702, - "friends_count":607, - "listed_count":1, - "favourites_count":113338, - "statuses_count":389, - "created_at":"Sat Nov 01 22:38:25 +0000 2014", - "utc_offset":null, - "time_zone":null, - "geo_enabled":true, - "lang":"tr", - "contributors_enabled":false, - "is_translator":false, - "profile_background_color":"C0DEED", - "profile_background_image_url":"", - "profile_background_image_url_https":"", - "profile_background_tile":false, - "profile_link_color":"1DA1F2", - "profile_sidebar_border_color":"C0DEED", - "profile_sidebar_fill_color":"DDEEF6", - "profile_text_color":"333333", - "profile_use_background_image":true, - "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg", - "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg", - "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/2855759795\/1480630085", - "default_profile":true, - "default_profile_image":false, - "following":null, - "follow_request_sent":null, - "notifications":null - }, - "geo":null, - "coordinates":null, - "place":null, - "contributors":null, - "is_quote_status":false, - "retweet_count":0, - "favorite_count":0, - "entities":{ - "hashtags":[], - "urls":[], - "user_mentions":[ - { - "screen_name":"kafammheppduman", - "name":"delirdim kanka", - "id":2855759795, - "id_str":"2855759795", - "indices":[ - 0, - 16 - ] - } - ], - "symbols":[] - }, - "favorited":false, - "retweeted":false, - "filter_level":"low", - "lang":"und" - }, - "user":{ - "id":774146932365070336, - "id_str":"774146932365070336", - "name":"Uyuyan Adam", - "screen_name":"saykoMenn", - "location":"Tarsus, T\u00fcrkiye", - "url":"http:\/\/connected2.me\/pmc1i", - "description":null, - "translator_type":"none", - "protected":false, - "verified":false, - "followers_count":414, - "friends_count":393, - "listed_count":0, - "favourites_count":9868, - "statuses_count":370, - "created_at":"Fri Sep 09 07:26:26 +0000 2016", - "utc_offset":null, - "time_zone":null, - "geo_enabled":false, - "lang":"tr", - "contributors_enabled":false, - "is_translator":false, - "profile_background_color":"F5F8FA", - "profile_background_image_url":"", - "profile_background_image_url_https":"", - "profile_background_tile":false, - "profile_link_color":"1DA1F2", - "profile_sidebar_border_color":"C0DEED", - "profile_sidebar_fill_color":"DDEEF6", - "profile_text_color":"333333", - "profile_use_background_image":true, - "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg", - "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg", - "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/774146932365070336\/1480283382", - "default_profile":true, - "default_profile_image":false, - "following":null, - "follow_request_sent":null, - "notifications":null - } -} -``` - - -**Like Delete / “Unlike” payload** - -```json -{ - "delete":{ - "favorite":{ - "tweet_id":696615514970279937, - "tweet_id_str":"696615514970279937", - "user_id":2510287578, - "user_id_str":"2510287578" - }, - "timestamp_ms":"1480437031205" - } -} -``` - -## Guides - -### Recovery and Redundency - -**Introduction**  - -With streaming high volumes of realtime Posts comes a set of best practices that promote both data reliability and data full-fidelity. When consuming realtime data, maximizing your connection time is a fundamental goal. When disconnects occur, it is important to automatically detect that and reconnect. After reconnecting it’s important to assess if there are any periods to backfill data for. The component that manages these details and consumes realtime Posts is only one part of a system with network, datastore, server, and storage concerns. Given the complexity of these systems, another best practice is to have different streaming environments, with at least separate streams for development/testing and production. - -Decahose comes with a set of features that help with these efforts. - -1. To support multiple environments, we can deploy [Additional Streams](#AdditionalStreams) for your account. These streams are independent of each other and have a different stream_label  to help differentiate them. -2. To help support maintaining a connection, each Decahose stream supports [Redundant Connections](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#additional-streams). The most common architecture is for a stream to have two connections, and on the client-side there are two independent consumers –ideally on different networks. With this design, there can be redundancy across the client-side networks, servers, and datastore pathways. Note that a full-copy of the data is served on each connection and the client-side must be tolerant of and manage duplicate data. -3. A '**heartbeat**' will be provided every 10 seconds; however, with the Decahose stream, the volume of data is high enough that even a small duration (e.g., a few seconds) of no Posts can indicate a connection issue. Therfore, both a 'data silence' and lack of a heartbeat can be used to detect a disconnect. - -Since disconnects will happen, the Decahose stream has a dedicated [Recovery](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#overview) and a [Backfill](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#backfill) feature to help recover data that was missed due to disconnections and other operational issues. - -#### Additional Streams - -Having additional Decahose streams is another way to help build reliability into your solution. Any additional streams are completely independent, having their unique endpoint. Each stream is assigned its own stream_label, and this label, along with your account name, are part of that stream’s URL. See the example below: - -https://gnip-stream.x.com/stream/sample10/accounts/:account\_name/publishers/twitter/:stream\_label.json - -The most common convention is to have a realtime stream dedicated for you production system, and an additional stream available for development and testing. Having a test/development stream enables Decahose customers to have a stream to test client consumer updates. While any (unique) label can be assigned to a stream, one convention is to use ‘prod’ for production stream, and ‘dev’ or ‘sandbox’ for an additional development stream. - -The number of streams, and their unique labels, is configurable by your account representative. - -**Redundant Connections** - -A redundant connection simply allows you to establish more than one simultaneous connection to the data stream. This provides redundancy by allowing you to connect to the same stream with two separate consumers, receiving the same data through both connections. Thus, your app has a hot failover for various situations, e.g. where one stream is disconnected or where your app’s primary server fails. - -The number of connections allowed for any given stream is configurable by your account representative. To use a redundant stream, simply connect to the same URL used for your primary connection. The data for your stream will be sent through both connections, with both stream connections represented on the stream dashboard. - -Note that for billing purposes, we deduplicate the activity counts you receive through multiple connections such that you are only billed for each unique activity once. Given the Decahose has two partitions, here's an example of how the connection count works below: - -Connect to decahose partition=1 -Connect to decahose partition=1 -Connect to decahose partition=2 - -The above situation yields a total of three connections – two connections to partition=1 and one connection to partition=2. Normally, you would want the same number of connections to each partition, so this example highlights a situation where the redundant connection to partition=2 has dropped and you want to further invstigate. - -**Recovery** - -#### Overview  - -Recovery is a data recovery tool (not to be used for primary data collection) that provides streaming access to a rolling 5-day window of recent X historical data. It should be utilized to recover data in scenarios where your consuming application misses data in the realtime stream, whether due to disconnecting for a short period, or for any other scenario where you fail to ingest realtime data for a period of time. - -#### Using Recovery  - -With the Recovery stream, your app can make requests to it that operate in the same manner as requests to the realtime streams. However, your app must specify parameters in the URL that indicate the time window you are requesting. In other words, a Recovery request asks the API for "Posts from time A to time B." These Posts are then delivered through your streaming connection in a manner that mimics the realtime stream, but at a slightly slower-than-realtime rate. See below for example: - - -"https://stream-data-api.x.com/stream/powertrack/accounts/someAccountName/publishers/twitter/powertrack.json?startTime=2023-07-05T17:09:12.070Z" - -Posts are delivered beginning with the first (oldest) minute of the specified time period, continuing chronologically until the final minute is delivered. At that point, aRecovery Request Completed message is sent through the connection, and the connection is then closed by the server. If your request begins at a time of day where little or no matching results occurred, there will likely be some period of time before the first results are delivered – data will be delivered when Recovery encounters matches in the portion of the archive being processed at that time. When no results are available to deliver, the stream will continue sending carriage-return, or "heartbeats", through the connection to prevent you from timing out. - -Recovery is intended as a tool for easily recovering data missed due to short disconnects, not for very long time periods like an entire day. If the need to recover data for long periods arises, we recommend breaking longer requests into shorter time windows (e.g. two hours) to reduce the possibility of being disconnected mid-request due to internet volatility or other reasons, and to provide more visibility into the progress of long requests. - -#### Data Availability - -You can use the Recovery feature to recover missed data within the last 24 hours if you are unable to reconnect with the 5 minute backfill window. - -The streaming recovery feature allows you to have an extended backfill window of 24 hours. Recovery enables you to ‘recover’ the time period of missed data. A recovery stream is started when you make a connection request using 'start\_time' and 'end\_time' request parameters. Once connected, Recovery will re-stream the time period indicated, then disconnect.   - -You will be able to make 2 concurrent requests to recovery at the same time, i.e. “two recovery jobs”. Recovery works technically in the same way as backfill, except a start and end time is defined. A recovery period is for a single time range. - -#### Backfill - -To request backfill, you need to add a backfillMinutes=N parameter to your connection request, where N is the number of minutes (1-5, whole numbers only) to backfill when the connection is made. For example, if you disconnect for 90 seconds, you should add backfillMinutes=2 to your connection request. Since this request will provide backfill for 2 minutes, including for the 30-second period before you disconnected, your _consumer app must be tolerant of duplicate data_. - -An example Decahose connection request URL, requesting a 5 minute backfill to partition 1, looks like: - -https://gnip-stream.x.com/stream/sample10/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition=1&backfillMinutes=5 - -**NOTES:** - -* You do have the option to always use ‘backfillMinutes=5’ when you connect, then handling any duplicate data that is provided. - -* If you are disconnected for more than five minutes, you can recover data using Recovery. - - - -**Recovering from Disconnect** - -Restarting and recovering from a disconnect involves several steps: - -* Determining length of disconnect time period. - * 5 minutes or less? - * If you have Backfill enabled for stream, prepare connection request with appropriate ‘backfillMinutes’ parameter. - * More than 5 minutes? - * If you have a Recovery stream, make a Recovery request for the disconnected time period (ideally with your current realtime rule set, using the Rules API if necessary). -* Request a new connection. - -When you experience disconnects or downtime, here are strategies to mitigate and recover in this scenario: - -1. **Implement backfill** - Backfill lets you reconnect from a point prior to disconnecting from a stream connection, and covers disconnects of up to 5 minutes. It is implemented by including a parameter in the connection request. - -2. **Consume a redundant stream from another location** - If the redundant stream can be streamed into the same live environment, deduplicating data, you will eliminate the need for recovery unless BOTH the normal stream and redundant stream experience simultaneous downtime or disconnects. If the redundant stream cannot be streamed live into the production environment, it can be written into a separate “emergency” data store. Then, in the event of disconnects or downtime on the primary stream connection, your system will have data on hand to fill in your primary database for the period of time where data is missing - -3. **Implement Recovery** - Where disconnects or downtime affect both the primary stream and redundant stream, use the Decahose Recovery to recover any data missed. The API provides a rolling window covering 5 days of the archive, and would be best utilized by requesting no more than an hour of that window at a time, and streaming it in. This is done in parallel to the realtime stream. Note that we do not have solutions for recovering Decahose data from beyond the 5 day window provided by Recovery, so it is important for you to utilize a redundant stream to ensure you have a complete copy of data on your side in the case of significant downtime on your side. - - -When you detect abnormal stored data volumes-  -Potential ways you can detect missing data where no disconnects or downtime occurred… - -1. Count inbound Posts - Your system should count the raw number of Posts you receive at the very beginning of your ingestion app, and then provide a way to compare those numbers to the number of Posts that reaches your final data store. Any differences can be monitored, and alert your team to issues causing data to be dropped after it is received. - -2. Analyze for abnormal stored volumes - You may also want to analyze the volumes of stored data in your final database to look for abnormal drops. This can indicate issues as well, although there will likely be circumstances in which drops in volume are normal (e.g. if the X platform is unavailable and people are not able to create Posts for some period of time). - -## API Reference - -### Decahose stream - -Jump to on this page - -[Methods](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#methods) - -[Authentication](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#authentication) - -[GET /\{stream-type}/:stream](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#get-stream-type-stream) - -[Replay API](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#replay-api) - -#### Methods - -| Method | Description | -| :--- | :--- | -| [GET /\{stream-type}/:stream](#Stream) | Connect to the data stream | - -#### Authentication[](#authentication- "Permalink to this headline") - - -All requests to the Volume Stream APIs must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. So confirm that your client is adding the "Authentication: Basic" HTTP header (with encoded credentials over HTTPS) to all API requests. - -#### GET \{stream-type}\:stream - -Establishes a persistent connection to the Firehose stream, through which the realtime data will be delivered. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **Connection Type** | Keep-Alive

This should be specified in the header of the request. | -| **URL** | Found on the stream's API Help page of your dashboard, using the following structure:

Decahose:

[https://gnip-stream.x.com/stream/sample10/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition=1](https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1) | -| **Partition (required)** | `partition=\{#}` \- Partitioning is now required in order to consume the full stream. You will need to connect to the stream with the partition parameter specified. Below is the number of partitions per stream:

* Decahose: 2 partitions | -| **Compression** | Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following:

Accept-Encoding: gzip | -| **Character Encoding** | UTF-8 | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | 10 requests per 60 seconds. | -| **Backfill Parameter** | If you have purchased a stream with Backfill enabled, you'll need to add the "backfillMinutes" parameter into GET request to enable it. | -| **Read Timeout** | Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds. | -| **Support for Tweet edits** | All Tweet objects will include Tweet edit metadata describing the Tweet's edit history. See the ["Edit Tweets" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) for more details. | - -#### Responses - -The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | Success | The connection was successfully opened, and new activities will be sent through as they arrive. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 406 | Not Acceptable | Generally, this occurs where your client fails to properly include the headers to accept gzip encoding from the stream, but can occur in other circumstances as well.

Will contain a JSON message similar to "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end." | -| 429 | Rate Limited | Your app has exceeded the limit on connection requests. | -| 503 | Service Unavailable | Twitter server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support or emergency if unable to connect after 10 minutes. | - -#### Example curl Request - -The following example request is accomplished using cURL on the command line. However, note that these requests may also be sent with the programming language of your choice: - -``` -curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/firehose/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition={#}" -``` -#### Replay API - -The Replay API is an important complement to realtime Volume streams. Replay is a data recovery tool that provides streaming access to a rolling window of recent X historical data. - - diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/edit-tweets.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/edit-tweets.mdx deleted file mode 100644 index 3fb6e654b..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/edit-tweets.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Edit Tweets -keywords: ["edit tweets enterprise", "enterprise edit tweets", "edit posts enterprise", "tweet edits enterprise", "edit metadata enterprise"] ---- -Enterprise endpoints have been updated to provide edited Post metadata. The _Edit Posts _feature was first introduced for testing among X employees on September 1, 2022. Starting on that date, eligible Posts were editable for 30 minutes and up to 5 times. _All objects for Posts created since September 29, 2022_ include Post edit metadata, even if the Post was never edited. Each time a Posts is edited, a new Post ID is created. A Post's edit history can be described by chaining these IDs together, starting with the original ID. Additionally, if any Post in the edit chain is deleted, all Posts in that chain are deleted as well.  - -These metadata details are included automatically. No request parameters are needed to include available edit history as part of the Post object.  - -With these new metadata, a developer can find out: - -* If a Post was edit eligible at the time of creation. Some Posts, such as those with polls or scheduled Posts, cannot be edited. -* Posts are editable for 30 minutes, and can be edited up to 5 times. For editable Posts, you can see if time for editing remains and how many more edits are possible. -* If you are viewing an edited version of a Post. In most cases, the API will return the most recent version of a Post, unless a specific past version is requested by Post ID. - -Three new Post attributes have been added at the root level: - -* **edit_history**  \- Provides all Post IDs associated with the edit history of the Post. The "initial\_tweet\_id" attribute indicates the original Post and the "edit\_tweet\_ids" attribute is an array that provides all IDs associated with its edit history. If the Post has not been edited, this array will contain a single ID. -``` -"edit_history": { -    "initial\_tweet\_id": "1283764123" -    "edit\_tweet\_ids": \["1283764123"\] -  } -``` -* **edit_controls** \- Provides attributes that indicate when the 30-minute edit window ends and how many potential edits remain.  -``` -"edit_controls": {   -     "editable\_until\_ms": 1660155761384 -     "edits_remaining": 3    -  } -``` -* **editable** \- Indicates whether a Post was eligible for editing when created.  - -"editable": true - -Most Posts are eligible. However, the following types of Posts are not:  - -* Post is promoted -* Post has a poll -* Post is a non-self-thread reply -* Post is a Retweet (note that Quote Tweets are eligible for edit) -* Post is nullcast -* Community Post -* Superfollow Post -* Collaborative Post - -**Example attributes for unedited Post** - - -The JSON below highlights edit metadata that is included for a Post posted after the edit Post feature was added. This example is for a Post that has no edit history.  - -Note that the `"edit_tweet_ids"` array has a single ID.  - -``` -{ - "created_at": "Wed Aug 16 18:29:02 +0000 2022", - "id": 1557433858676740098, - "id_str": "1557433858676740098", - "text": "I wonder if I will every use teh edit button", - "edit_history": { - "initial_tweet_id": "1557433858676740098", - "edit_tweet_ids": ["1557433858676740098"] - }, - "edit_controls": { - "editable_until_ms": 1660155761384, - "edits_remaining": 5 - }, - "editable": true -} -``` - -**Example attributes for an edited Post** - -The JSON below highlights edit metadata that is included for a post posted after the edit Post feature was added. This example is for a Post that has had a single edit.  - -Note that the `"edit_tweet_ids"` array has two IDs, one for the original Post and one for the edited update.  - -``` -{ - "created_at": "Wed Aug 16 18:35:42 +0000 2022", - "id": 1557445923210514432, - "id_str": "1557445923210514432", - "text": "I wonder if I will ever use the edit button", - "edit_history": { - "initial_tweet_id": "1557433858676740098", - "edit_tweet_ids": ["1557433858676740098", "1557445923210514432"] - }, - "edit_controls": { - "editable_until_ms": 1660155761384, - "edits_remaining": 4 - }, - "editable": true -} -``` - -**Compliance support** - -The [Compliance Firehose](/x-api/enterprise-gnip-2.0/fundamentals/firehouse) and the v2 [batch compliance endpoint](/x-api/compliance/batch-compliance/introduction) have both been updated to provide edit Post support:  - -A new "tweet_edit" event type has been added to the Compliance Firehose.  - -``` -{ - "tweet_edit": { - "id": , - "initial_tweet_id": , - "edit_tweet_ids": [, , ...], - "timestamp_ms": "" - } -} -``` diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/engagement-api.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/engagement-api.mdx deleted file mode 100644 index 8687919c0..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/engagement-api.mdx +++ /dev/null @@ -1,816 +0,0 @@ ---- -title: Engagement API -keywords: ["Engagement API", "enterprise Engagement API", "engagement metrics", "engagement data", "enterprise engagement", "GNIP engagement"] ---- -## Overview - -[`Enterprise`](https://developer.x.com/en/products/x-api/enterprise) - -_This is an enterprise API available within our managed access levels only. To use this API, you must first set up an account with our enterprise sales team. [Learn more](/x-api/enterprise-gnip-2.0/enterprise-gnip)_ - -The Engagement API provides access to Post impression and engagement metrics. While most metrics and endpoints require you to authenticate using [OAuth 1.0a User Context](/resources/fundamentals/authentication), you can access public Favorite, Retweet, Reply, and Video Views metrics using [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#oauth-2-0) and the /totals endpoint.   - -**Note:** You may observe differences between reported data on some of the X web dashboards, and the data reported in the Engagement API. These differences occur because the web dashboards typically only show engagements and/or impressions that occurred within the selected time range. For example, a web dashboard may show engagement on Posts within the span of a calendar month, while the Engagement API may show engagements that fall beyond the span of that month, but within the time range requested. The Engagement API should be seen as the valid source, in these cases. -  - -### Request endpoints - -The Engagement API has three endpoints: - -#### Current Totals: [/totals] - -* Requests return a total metric for impressions and a total metric for engagements for the desired Posts -* Limited to the following metrics: Impressions, Engagements, Favorites, Replies, Retweets, Quote Tweets, and Video Views -* Supports the ability to retrieve **Impressions** and **Engagements** metrics for Posts created **within the last 90 days** using OAuth 1.0a User Context -* Supports the ability to retrieve **Favorites, Retweets, Quote Tweets, Replies,** and **Video Views** metrics for **any Post** using OAuth 2.0 Bearer token -* The results are based on the current total of impressions and engagements at the time the request is made -* Ideal for powering a dashboard report and for calculating engagement rates across a variety of @handles -* Supports requesting metrics for up to 250 Posts per request -   - -#### Last 28 hours: [/28hr] - -* Requests can return a total metric for impressions, a total metric for engagements, and breakdown of individual engagement metrics that have occurred in the last 28 hours -* Data can be grouped by Post ID, and in time-series in aggregate, by day, or by hour -* Ideal for tracking the performance of recently created content -* Supports all available metrics -* Supports requesting metrics for up to 25 Posts per request -   - -#### Historical: [/historical] -* Requests can return impressions, engagements, and a breakdown of individual engagement metrics for the most recent one year, based on the engagement time (not the Post creation time). -* Requests support a start date and end date parameter, providing flexibility to narrow into a specific time frame up to 4 weeks in duration. -* Post engagement data is limited to only 365 days in the past. -* Data can be grouped by Post ID, and in time-series in aggregate, by day, or by hour. -* Ideal for evaluating recent performance against a historical benchmark or developing a historical picture of an @handle’s performance. -* Supports all available metrics. -* Supports requesting metrics for up to 25 Posts per request. - -### Available metrics - -The table below describes the types of metrics that can be accessed through the Engagement API. - -Please check out our [Interpreting the metrics page](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#interpreting-the-metrics) to learn more about the below metrics. - -| Metric | Endpoint Availability | User Context Required | Description | -| :--- | :--- | :--- | :--- | -| impressions | All | Yes | A count of how many times the Post has been viewed. This metric is only available for Posts that have been posted within the past 90 days. | -| engagements | All | Yes | A count of the number of times a user has interacted with the Post. This metric is only available for Posts that have been posted within the past 90 days. | -| favorites | All | Yes - /28hrs & /Historical

No - /totals | A count of how many times the Post has been favorited. | -| retweets | All | Yes - /28hrs & /Historical

No - /totals | A count of how many times the Post has been Retweeted. | -| quote\_tweets | /totals | No - /totals | A count of times a Post has been Retweeted with a comment (also known as Quote). | -| replies | All | Yes - /28hrs & /Historical

No - /totals | A count of how many times the Post has been replied to. | -| video\_views | All | Yes - /28hrs & /Historical

No - /totals | A count of how many times a video in the given Post has been 50% visible for at least two seconds.

Video views are only available for Posts that are 1800 days old or less. If you try to request video views for any Posts older than 1800 days, you will receive the following object within your response, along with a separate object that contains any other metrics that you requested:

"unsupported\_for\_video\_views\_tweet\_ids": \["TWEET\_ID"\]

**Please note:** You may see a discrepancy between the video views metric displayed in the X owned and operated platforms (mobile app and website) and the number that you receive via the /28hr and /historical endpoints.

* The video views displayed in the X user interface and with the /totals endpoint will display the video view aggregated across all Posts in which the given video has been posted. That means that the metric displayed in the UI includes the combined views from any instance where the video has been Retweeted or reposted in separate Posts. This metric does not include video views on gifs.
* The video views provided by the /28hr and /historical endpoints will just include those views generated by the specific Post for which you are pulling metrics. This metric does not include video views on gifs. | -| media\_views | /28hr /historical | Yes | A count of all views (autoplay and click) of your media counted across videos, gifs, and images. | -| media\_engagements

([formerly Media Clicks](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#recent-changes-to-the-engagement-api)) | /28hr /historical | Yes | A count of how many times media such as an image or video in the Post has been clicked. | -| url\_clicks | /28hr /historical | Yes | A count of how many times a URL in the Post has been clicked. | -| hashtag\_clicks | /28hr /historical | Yes | A count of how many times a hashtag in the Post has been clicked. | -| detail\_expands | /28hr /historical | Yes | A count of how many times the Post has been clicked to see more details. | -| permalink\_clicks | /28hr /historical | Yes | A count of how many times the permalink to the Post (the individual web page dedicated to this Post) has been clicked. | -| app\_install\_attempts | /28hr /historical | Yes | A count of how many times an App Install event has occurred from the Post | -| app\_opens | /28hr /historical | Yes | A count of how many times an App Open event has occurred from the Post. | -| email\_tweet | /28hr /historical | Yes | A count of how many times the Post has been shared via email. | -| user\_follows | /28hr /historical | Yes | A count of how many times the User (Post author) has been followed from this Post. | -| user\_profile\_clicks | /28hr /historical | Yes | A count of how many times the User (Post author) has had their profile clicked from this Post. | - -### Engagement groupings - -Groupings enable custom organization of the returned engagement metrics. You can include a maximum of 3 groupings per request. You can choose to group the metrics by one or more of the following values: - -_All three endpoints support:_ - -* tweet.id -* engagement.type -   - -_The `/28hr` and `/historical` can provide time-series metrics, and thus support:_ - -* engagement.day -* engagement.hour - -To learn more about grouping, please visit the [Engagement API Grouping](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings) page within the Guides section. - -## Guides - -### Developer getting started guide - -#### Introduction - -The purpose of this documentation is to provide developers an introduction to integrating with the Engagement API. We’ll start off by discussing the ‘whys’ of integrating, then start digging into the technical ‘how’ details. - -##### **What does the Engagement API provide?** - -* The Engagement API provides impression and engagement data for any X account’s owned Posts from the last 90 days, assuming that account has authorized your App to request metrics on their behalf using [3-legged OAuth](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). This powerful, yet easy-to-implement solution gives immediate access to impressions and deep engagements such as URL clicks, #hashtag clicks, and many more. -* The Engagement API provides total aggregate metrics for favorites, Retweets, Quote Tweets, replies, and video views views for any Post. This can be used as a powerful way to get basic engagement data about any Post or collection of Posts. -* The Engagement API delivers new value to social listening, marketing, and publishing platforms by allowing customers to measure ROI on X by effectively measuring the performance of content using 15+ performance metrics. -* The Engagement API is a request/response API that allows app developers to send requests with Post IDs, desired metrics, and a time frame, for which the API instantly returns data. -   - -##### **Why integrate? Example use-cases** - -* Understand the total reach of your content to see how many people view it. See how many people view videos, click on links, click on hashtags, or install my apps. -* Generate both total and time-series engagement metrics. -* Understand basic engagement metrics (favorites, Retweets, Quote Tweets, replies) about any public Post. -* Use these metrics to determine what types of Posts work so I can post them more often and get more impressions and more engagements for my content. -* Automate marketing behavior (such as Retweeting content from a different owned account) every time one of my Posts reaches 100 Likes, or another threshold. -* Benchmark and compare my campaigns against each other as a tool for A/B testing. -* Analyze what type of content resonates for my customer service department to determine how and when to respond. -* Show analytics for content that is published from my platform. -   - -The [Engagement API was launched in 2016](https://blog.x.com/official/en_us/a/2016/gnip-s-engagement-api-is-now-generally-available.html) and was the first X API to provide these in-depth engagement metrics at scale. The Engagement API is easy to use and enables customers to automate the process. Here is a case study describing an example integration: - -* [Measuring campaign success with the Red Cross](https://blog.x.com/developer/en_us/topics/spotlight/2016/measuring-campaign-success-with-the-red-cross.html)[](https://simplymeasured.com/blog/true-twitter-impressions-and-url-clicks-new-from-simply-measured/#sm.0007werel134td8zqf02m2mduumr6) - -Now that we’ve explored the ‘whys’ of the Engagement API, let’s start digging into the technical details. - - -#### Integrating the Engagement API - -##### **Introduction to API** - -The Engagement API is a simple RESTful API that receives requests encoded in JSON and responds with engagement metrics encoded in JSON. Requests consist three main parts (follow links for more documentation): - -* Array of **_Post IDs_**. -* Array specifying the [metric types](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#EngagementTypes) of interest. Types include things such as ‘impressions’, ‘retweets’, ‘hashtag\_clicks’, and ‘user\_follows’. -* [Engagement groupings](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings), which is a JSON structure indicating how you want the engagement data arranged in the API response. - - -In many situations, the Engagement Types and Groupings will remains relatively constant from request to request, with only the Post IDs being updated. - -The Engagement API provides [three endpoints](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#RequestEndpoints): - -* **Totals** \- Provides grand totals of engagements for Posts. Some metrics are available for all Posts, while others are only available for the past 90 days. -* **28 hour** \- Provides time-series engagement metrics from the last 28 hours. -* **Historical** \- Provides time-series engagement metrics for up to four consecutive weeks for Posts posted since September 1, 2014. - - -The **/totals** endpoint supports requesting metrics for up to **250 Posts per request**. The **/28hour** and **/historical** endpoints support **25 per request**. - -After discussing getting access to the Engagement API, we’ll walk through making an API request, provide an OAuth overview, and provide links to other technical resources. - -##### **Getting API access** - -If you are reading this document, you have most likely already obtained access to the Engagement API. If not, please reach out to your Enterprise account manager, or apply for Enterprise access [here](/x-api/enterprise-gnip-2.0/enterprise-gnip). - -The first step is creating a [X app](/resources/fundamentals/developer-apps) using an approved developer account via the [Developer Console](/resources/fundamentals/developer-portal).  Your account manager will need the numeric App ID associated with this application to provide access. If you need to apply for a developer account, you can do so [here](/resources/fundamentals/developer-apps). - -##### **Making a request** - -The good news is that making requests to the Engagement API is simple. For our request, we’ll ask it for total Retweets, Quote Tweets, Favorites, and replies, for the following two [@XDevelopers](https://x.com/XDevelopers) Posts: - -> 1/ Today we’re sharing our vision for the future of the X API platform![https://t.co/XweGngmxlP](https://t.co/XweGngmxlP) -> -> — Twitter Dev (@TwitterDev) [April 6, 2017](https://x.com/TwitterDev/status/850006245121695744) - -> Don’t miss the Posts about your Post. -> -> Now on iOS, you can see Retweets with comments all in one place. [pic.x.com/oanjZfzC6y](https://t.co/oanjZfzC6y) -> -> — X (@X) [May 12, 2020](https://x.com/status/1260294888811347969?ref_src=twsrc%5Etfw) - -The first step is constructing the API request in JSON, consisting of these two Post IDs placed in an array, an array of engagement types of interest, and a custom-named “groupings” JSON object that indicates how we want the metrics arranged in the response. Here is what our request looks like: - -```json -{ - "tweet_ids": [ - 1260294888811347969, 850006245121695744 - ], - "engagement_types": [ - "retweets", "quote_tweets", "favorites", "replies" - ], - "groupings": { - "engagement-types-by-id": { - "group_by": [ - "Tweet.id", "engagement.type" - ] - } - } -} -``` - -To retrieve these total metrics, we POST this JSON request to the https://data-api.x.com/insights/engagement/totals endpoint. - -We’ll include the following headers to indicate that our request is encoded in JSON, and that it is Gzipped (request bodies can get big): - -* Content-Type: application/json -* Accept-Encoding: gzip -   - -When making requests we authenticate using OAuth, which we’ll discuss more in the next section. - -The API returns the following payload: - -```json -{ - "grouping name": { - "1260294888811347969": { - "favorites": "17111", - "quote_tweets": "3254", - "replies": "1828", - "retweets": "5218" - }, - "850006245121695744": { - "favorites": "492", - "quote_tweets": "66", - "replies": "42", - "retweets": "324" - } - } -} -``` - - -Note that the response has our requested metrics in the structure described by the “groupings” definitions, with metrics listed by Post ID first, then by engagement type on the next level. - -That was pretty simple. If you are new to authenticating with OAuth, check out the next section. - - -#### Authenticating with OAuth - -OAuth is an authentication standard that is very common in the technology industry.  If you are already using OAuth (perhaps with other X APIs) then you are likely using a language-specific OAuth package that abstracts away all the gnarly details. If you are new to OAuth, please visit our [Oauth with the X API](/resources/fundamentals/authentication) page or head directly to the [https://oauth.net](https://oauth.net/) to learn more. Then we recommend that you find an OAuth package for your integration language of choice and start there. With these packages, the path to authenticating typically means configuring your keys and tokens, creating some sort of HTTP object, then making requests with that object. - -For example, in the Ruby world, the following pseudo-code represents a recipe to build an OAuth-enabled app using the Ruby gem ‘oauth’ and making a POST request:   - -```js -require 'oauth' - -#Assemble JSON request (as above). -request = make_json_request() - -#Build an app consumer object with my app consumer key and secret. -consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => ‘https://data-api.x.com’}) -#Build a user token with tokens provided by account providing permission. If making app-only #request (checking Tweets that do not require permission with /totals endpoint), this step can be #skipped. -token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']} - -#Create oauth-enabled app object. -app = OAuth::AccessToken.from_hash(consumer, token) -#Make POST request. -result = app.post(“/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"}) -``` - -The Engagement API supports both application-only and user-context authentication. If you are collecting engagement metrics for unowned public Posts with the /totals endpoint then no user permission is required and you can use application-only authentication. In this case, you’ll use only your app key and secret to authenticate. - -OAuth also allows an app to make an API request “on behalf of another user”, using tokens that relate to the user. If you are generating Engagement metrics for owned Posts, ie Posts that were published by a user whom you have user tokens for, you will be making requests with a user context, meaning authenticating with both your app keys and user-specific access tokens. These user access tokens are typically supplied with the '[Sign-in with X](/resources/fundamentals/authentication#log-in-with-x)' process or acquired directly from the user (please note that you must use [twurl](https://github.com/xdevplatform/xurl) if you acquire the tokens directly from the user). Once the user provides their tokens, they do not expire and can be used with the Engagement API to make requests on their behalf,  as long as the user doesn't reset their tokens or change their password, in which case they will have to provide you the new tokens. - -You can review which metrics require which authentication via [this table](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings). -  - -### Selecting an Engagement API Endpoint - -The Engagement API provides three distinct endpoints: - -* **[Totals](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement)** - provides grand totals of select metrics from owned 'owned' or 'unowned' Posts. Some metrics are available for all Posts, while others are only available for Posts published in the last 90 days. Supports 250 Posts per request. -* **[28 hour](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement)** - provides time-series Engagement metrics for ‘owned’ Posts from the last 28 hours. Supports 25 Posts per request. -* **[Historical](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement-historical)** \- provides time-series Engagement metrics for up to four consecutive weeks for ‘owned’ Posts posted since September 1, 2014. Supports 25 Posts per request. -   - -Each endpoint has its own unique characteristics. Whether you are planning to use all three, or are trying to decide which one best matches your use case, it’s important to understand the differences between them. - -Below we introduce some key concepts, further explore the three endpoints, and then present example use cases that map generally to a specific endpoint. Our hope is that this information will help you more efficiently integrate all three, or help you decide which single endpoint best fits your mission. -  - -#### Key concepts - -There are several key concepts that help illustrate the different features of, and data provided by, the three Engagement API endpoints. -  - -##### Impressions and engagement metrics - -Impressions represent the number of times that a given Post has been viewed on the X platform in an organic context. Impressions generated from Posts that are seen in a Promoted or Paid context are not included. Before the Engagement API, Post impressions represented only a measure of potential views. It was based on counting followers of the author’s account and those of any account Retweeting the content. It did not take into account the common situation when a given user does not actually see the Post. - -The impression metrics generated by the Engagement API is an actual measure of the number of times a Post has been rendered for display. If a follower of your account misses your Post, it does not count as an impression. - -The Engagement API provides metrics on 14 unique engagement [metric types](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#available-metrics), each representing a distinct action a user can take when presented a Post. These include Retweeting, Liking, Replying, clicking on entities like #hashtags, links and media, following the author, and viewing the author’s profile. All of these individual actions are rolled up into a single Engagements metric. - - -##### Owned and unowned X content - -The Engagement makes a clear distinction between owned and unowned Posts. Owned Posts are Posts that are posted from your account, or Posts that you have obtained permission to request Engagement data for. As with other X APIs, you obtain permission by having other X users/accounts share access tokens that enable you to make API requests on their behalf. A common way to obtain these tokens is with the [‘Sign in with X’ process](/resources/fundamentals/authentication#log-in-with-x). - -The /totals endpoint provides engagement data for both owned and unowned Posts. For unowned Posts, you can request engagement metrics that are publicly available in a Post display: Favorite, Retweet, and Reply. For these metrics, what the Engagement API brings to the table is the ability to retrieve these metrics at scale in an automated way. For owned Posts, the /totals endpoint also provides Impression and (total) Engagement metrics. - -The /28hr and /historical endpoints provide metrics for owned Posts only, meaning that you have to pass along user context when making the request to these endpoints. - - -##### Total and time-series engagement Data - -The /totals endpoint provides, as its name implies, only grand totals for its engagement types. Its numbers represent the up-to-date totals since the Post was posted. If a Post was just posted and you repeatedly request its metrics, these totals will commonly change with each request. - -The /28hr and /historical endpoints can provide both grand totals and time-series data. When requesting time-series data, the engagement metrics can be rolled up into daily or hourly data.    - -See our documentation on [engagement groupings](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings) for how to request time-series data with the /28hr and /historical endpoints. - - -#### Endpoints and example use cases - -Given the characteristics and differences discussed above, each individual endpoint generally maps to different types of use cases. To help you decide which endpoint best serves your particular use case, below are some example user statements and the endpoint that best satisfies it. - -##### **/totals** - -* I only need access to some metric types (Impressions, Engagements, Favorites, Retweets, Quote Tweets, Replies, and Video Views). -* I need access to basic engagement data for any Post, not just owned Posts. -* I want to compare performance against a competitor. -* I want to track basic engagement stats for a hashtag or campaign that includes Posts that I don’t own. -* I don’t need data broken out by day or hour, I just need the current total when I make a request. -* I need a single metric to show in a report or dashboard and don’t want to store any data. -* I want to show data at page load time, and just need to make a request and get a response. -* I need access to get data for hundreds of thousands or millions of Posts per day. -   - -##### **/28hr** - -* I need access to all 17 metric types. -* I want to show data for very recent Posts posted in last 28 hours. -* I have a job that runs once a day to get data that I care about and only need to get data for the last day. -* I need to have metrics broken out by day or hour. -* I want to show time-series breakouts of activity by hour in a dashboard. -* I need high access for hundreds of thousands to Posts per day -* I have storage capabilities and can refresh data once per day and keep a running tally. -   - -##### **/historical** - -* I need access to all 17 metric types. -* I need to get historical data for Posts created all the way back to September 2014. -* I want to show detailed historical analysis that compares campaigns. -* I need to have metrics broken out by day or hour. -* I don’t need high access to the Engagement API and only need to get data for a few hundred or thousand Posts per day. - - -### Engagement API key characteristics - -* **RESTful API** serving JSON data, supporting POST requests with JSON data bodies. -* **Types of Requests:** Client apps may make the following types of requests: - * **Total engagements** \-- HTTP POST request to /totals endpoint - * **Last 28-hour engagements** \-- HTTP POST request to /28hr endpoint - * **Historical engagements** \-- HTTP POST request to /historical endpoint -* **OAuth authentication:** - * [OAuth 1.0 User Context](/resources/fundamentals/authentication): All available metrics are available for Posts that are owned by a user that has authorized your App using [3-legged OAuth](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens). You must use that user's Access Tokens when making your request.[](/resources/fundamentals/authentication) - * [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#oauth-2-0): Select metrics (Retweets, Quote Tweets, Replies, Favorites, and Video Views) are available for any public Post.  -* **Request metadata and structure**: Request data is a JSON object consisting of a Post ID array, an array of engagement types, and an engagement grouping structure. -* **Posts per request:** - * /totals endpoint: 250 Post IDs - * /28hr endpoint: 25 Post IDs - * /historical endpoint: 25 Post IDs -* **Engagement metrics availability:** - * **/totals** -- Metric totals since when Post was posted. Impressions and Engagements are available for Posts published in the last 90 days, while Retweets, Quote Tweets, Replies, Favorites, and Video Views are available for all Posts. - * **/28hr** -- Last 28 hours from time of request. - * **/historical** -- Any 28-day period starting September 1, 2014. -* **Metric types**: Each request includes an array of [Metric Types](http://support.gnip.com/apis/engagement_api/overview.html#EngagementTypes). The availability of these depends on the endpoint and, if requesting from the /totals endpoint, on whether Posts are user-permissioned. - * /totals endpoint: - * All Posts: Favorites, Retweets, Quote Tweets, Replies, and Video Views - * Requires OAuth 1.0a User Context: Impressions, Engagements, Favorites, Replies, and Retweets - * /28hr and /historical endpoints (Requires OAuth 1.0a User Context with Post owner's Access Token): Impressions, Engagements, Favorites, Replies, Retweets, URL Clicks, Hashtag Clicks, Detail Click, Permalink Clicks, Media Clicks, App Install Attempts, App Opens, Post Emails, Video Views, and Media Views -* **Engagement groupings:** Each request includes an array of [Engagement Groupings](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings). With these groupings you can customize how the returned metrics are organized. Up to three groupings can be included with each request. Metrics can be organized by the following values: - * All endpoints: Post ID, Engagement Type - * /28hr and /historical endpoints: These endpoints provide time-series if these additional groupings are specified: Engagement Day, Engagement Hour -* **Integration Expectations:** Your team will be responsible for the following. - * Creating and maintaining a client app that can send HTTP requests to the Engagement API that returns engagement metrics for Post ID included in request. -* **Limitations** -* Video views are only available for Posts that are 1800 days old or less. - - -### Authenticating with the Engagement API - - ->**Please note**:  -> ->X needs to enable access to the Engagement API for your developer App before you can start using the API. To this end, make sure to share the App ID that you intend to use for authentication purposes with your account manager or technical support team. - -There are two authentication methods available with the Engagement API: [OAuth 1.0a](/resources/fundamentals/authentication#oauth-1-0a-2) and [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only).  - -**OAuth 2.0 Bearer Token** (also referred to as “application-only”) allows you to access publicly available engagement metrics. This authentication method can be used to get total counts for Favorites (aka Likes), Retweets, Quote Tweets, Replies, and video views for any publicly available Posts when making requests to the [/totals endpoint](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement-totals).  - -**OAuth 1.0a** (also referred to as “user context”) allows you to make requests on behalf of a user and access private engagement metrics that belong to the user in question.  - -This authentication method is required for: - -* All requests sent to the [/28hr endpoint](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement-28hr) and [/historical endpoint](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement-historical) -* Accessing any of the following private metrics: Impressions, Engagements, Media Views, Media Engagements, URL Clicks, Hashtag Clicks, Detail Expands, Permalink Clicks, App Install Attempts, App Opens, Email Post, User Follows, and User Profile Clicks - -When sending a request with OAuth 1.0a, you need to include the Access Tokens (Access Token and Secret) of the user who owns the Post or protected resource of interest. If you do not provide the correct user Access Tokens when requesting protected user data, the Engagement API will return a `403 Forbidden` error. - -The Engagement API will not allow you to fetch engagement data for [protected Posts](https://help.x.com/en/safety-and-security/public-and-protected-tweets), even if you are authenticating on behalf of the user who owns these Posts. Attempting to do so will return a `400 Bad Request` error, with the message `"Tweet ID(s) are unavailable"`. - -If you are sending a request on behalf of your own X account (in other words, the account that owns the developer App), you can generate the required Access Tokens directly from within the [Developer Console](https://developer.x.com/en/portal/projects-and-apps), under the “Keys and tokens” tab for the developer App. - -If you are making a request on behalf of any other user, you will need to use the 3-legged OAuth flow to obtain the required Access Tokens. The following documentation contains more information on how to do this: [OAuth 1.0a: how to obtain a user’s access tokens](/resources/fundamentals/authentication#oauth-1-0a-2). - -For additional examples, including how to authenticate using OAuth 1.0a, check out[XDevelopers sample Python code for the Engagement API](https://github.com/xdevplatform/enterprise-scripts-python/tree/master/Engagement-API). - - -### Recent changes to the Engagement API - -The Engagement API delivers invaluable impression and engagement metrics that enable you to monitor the performance of your activity on X. In our continual effort to enable marketing decisions based on our data, we are excited to share recent changes to the Engagement API that provide greater consistency with metrics across all of X.   - -We recently deployed changes to modernize the Engagement API to use the same metrics aggregation methodology in use by the X analytics dashboard (analytics.x.com). We took a thoughtful approach to try and minimize breaking API changes when rolling out these new metrics and deployed the first set of changes on October 9, 2017. These changes improve consistency from all of the places you or your customers might monitor your performance on X. Please see the detailed outline of the changes below: - -| | | -| :--- | :--- | -| **Metric** | **Change** | -| engagements | We’ve updated the metrics that roll into overall engagements to match consistency with the Post analytics dashboard. Engagements measures “times people interacted with this Post”.

For Posts that include media like a video or a GIF, the engagements metric will no longer include media views. Media views can now be accessed in a new metric, _media_views_. | -| media_clicks* | This metric has been replaced by a new metric called “_media_engagements_”. | -| video_views | As of July 6th, 2018, this metric is now available for 'unowned' Posts via the [/totals](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement) endpoint. This means that you can access the video views for **all** Posts by using app-only authentication. 

You can only request video views that are younger than 1800 days old. If you try to request video views for a Post older than 1800 days, you will receive the following:

"unsupported\_for\_video\_views\_tweet\_ids": \["TWEET\_ID"\]

**Please note** that it will differ from media\_views in that video\_views relies on the MRC standard of 50% of the video in view for at least two seconds.

**Also,** note that you may see a discrepancy between the video views metric displayed in the X owned and operated platforms (mobile app and website) and the number that you receive via the /28hr and /historical endpoints.

* The video views displayed in the X user interface and that delivers using the /totals endpoint will display the video view aggregated across all Posts in which the given video has been posted. That means that the metric displayed in the UI includes the combined views from any instance where the video has been Retweeted or reposted in separate Posts.
* The video views provided by the /28hr and /historical endpoints will just include those views generated by the specific Post for which you are pulling metrics. | -| media_views | This includes all views (autoplay and click) of your media counted across videos, vines, gifs, and images.

**Please note** that Posts with images do not show a media_views metric in the analytics dashboard but will be returned in the Engagement API. | -| media_engagements* | This includes the number of clicks on your media across videos, vines, gifs, and images. This metric is replacing _media_clicks_. | -| quote_tweets | As of July 7th, 2020, this metric is now available for 'unowned' Posts via the /totals endpoint. This means that you can access the Quote Post count for all Posts by using app-only authentication. | - - -### Interpreting the metrics - -**Note:** You may observe differences between reported data on some of the X web dashboards, and the data reported in the Engagement API. These differences occur because the web dashboards typically only show engagements and/or impressions that occurred within the selected time range. For example, a web dashboard may show engagement on Posts within the span of a calendar month, while the Engagement API may show engagements that fall beyond the span of that month, but within the time range requested. The Engagement API should be seen as the valid source, in these cases. -  - -#### Impressions and engagement data - -The Engagement API delivers **organic** impressions and engagement data. - -Impressions represent the number of times that a given Post has been viewed on the X platform in an organic context. Impressions generated from Posts that are seen in a Promoted or Paid context are **not** included. - -Engagements represent the number of times that a given Post was engaged upon by a viewer in both an **organic** and **promoted** context. Engagements include, but are not limited to, Retweets, Favorites, Replies, URL Clicks, Hashtag Clicks, Mention Clicks, and Media Views. For the full list of included engagement actions, please see the Engagement Data section.  - -In order to calculate a baseline engagement rate, please use the total number of engagements divided by the total number of impressions for a given Post for the time period you are analyzing. - -Impression and engagement data can only be retrieved for Posts from owned @handles, or @handles that have authorized your application to view details about their Posts.  Internally, the Engagement API will track the number of unique @handles that have been requested against the contracted @handle limit.  It's recommended to also track the @handle request usage on the client side throughout the month.   - - -#### Video metrics - -There are a couple of different metrics that represent impressions of media within X. The first of which is our video views metric, which relies on the MRC standard of 50% of the video in view for at least two seconds. The second is Media Views, that includes all views (autoplay and click) of your media counted across videos, vines, gifs, and images. - -The video views metric is available for owned Posts via the /28hour and /historical endpoints, as well as for all unowned Posts via the /totals endpoint.  - -While the video views metric within the X user interface is using the same MRC standard, please note that you may see a discrepancy between the video views metric displayed in the X owned and operated platforms (mobile app and website) and the number that you receive via the different Engagement API endpoints. - -* The video views provided by the /totals endpoint and the X user interface will display the video view aggregated across all Posts in which the given video has been posted. That means that the metric delivered via /totals and displayed in the X UI includes the combined views from any instance where the video has been Retweeted or reposted in separate Posts. -* The video views provided by the /28hour and /historical Engagement API endpoints will just include those views generated by the specific Post for which you are pulling metrics.  -   - -Please note that we do not deliver video views for Posts that are older than 1800 days. Instead, we deliver an object that lists the Posts that are older than 1800 days. You will still receive all other metrics for your requested Posts in a separate object. Here is an example response: - -```json -{ - "unsupported_for_video_views_tweet_ids": [ - "479311209565413376", - "477139122520219648" - ], - "grouping name": { - "479311209565413376": { - "favorites": "69", - "impressions": "1692", - "retweets": "142", - "video_views": "0" - }, - "477139122520219648": { - "favorites": "10", - "impressions": "1023", - "retweets": "6", - "video_views": "0" - }, - "1397568983931392004": { - "favorites": "268", - "impressions": "26803", - "retweets": "56", - "video_views": "17902" - } - } -} -``` - -The Media Views metric is only available for owned Posts with the /28hour and /historical endpoints. - - -### Engagement API groupings - -Groupings enable custom organization of the returned engagement metrics. You can include a maximum of 3 groupings per request. You can choose to group the metrics by one or more of the following values: - -_All three endpoints support:_ - -* tweet.id -* engagement.type -   - -_The `/28hr` and `/historical` can provide time-series metrics, and thus support:_ - -* engagement.day -* engagement.hour - -Groupings are honored serially, so that you can change the desired result format by changing the order of your `group_by` values. Groupings that contain four `group_by` values will only be supported in one of the following two formats: -  -```bash -"group_by": [ - "tweet.id", - "engagement.type", - "engagement.day", - "engagement.hour" - ] -``` - -OR - -```bash -"group_by": [ - "engagement.type", - "tweet.id", - "engagement.day", - "engagement.hour" -] -``` - -For example, if you want to generate grand totals of metric types, include the following “groupings” specification as part of your request (and see the [API Reference](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement) page for more information on assembling requests): -  -```json -{ - "engagement_types": [ - "favorites", - "replies", - "retweets" - ], - "groupings": { - "Grand Totals": { - "group_by": [ - "engagement.type" - ] - } - } -} -``` - -With this grouping, the Engagement API’s JSON response will include a root-level `"Grand Totals"` attribute which contains grand totals by metrics type: -```json -{ - "Grand Totals": { - "favorites": "12", - "replies": "2", - "retweets": "2" - } -} -``` - -To generate a 4-hour time-series of metrics for a single Post grouped by Post IDs, the following Grouping specification would be part of the request: - -```json -{ - "start": "2016-02-10T17:00:00Z", - "end": "2016-02-10T21:00:00Z", - "tweet_ids": [ - "697506383516729344" - ], - "engagement_types": [ - "impressions", - "engagements" - ], - "groupings": { - "Tweets_MetricType_TimeSeries": { - "group_by": [ - "tweet.id", - "engagement.type", - "engagement.hour" - ] - } - } -} -``` - -With this grouping, the Engagement API’s JSON response will include a root-level `"Tweets_MetricType_TimeSeries"` attribute which contains the metrics broken down by Post ID, then metric type, and the corresponding hourly time-series: - -```json -{ - "Tweets_MetricType_TimeSeries": { - "697506383516729344": { - "impressions": { - "2016-02-10": { - "17": "551", - "18": "412", - "19": "371", - "20": "280" - } - }, - "engagements": { - "2016-02-10": { - "17": "8", - "18": "6", - "19": "3", - "20": "0" - } - } - } - } -} -``` - -## Frequently asked questions - -`Enterprise` - -### Engagement API - - - - Access to the Engagement API is provisioned through an enterprise subscription.  Please fill out [this form](/x-api/enterprise-gnip-2.0/enterprise-gnip) to get in touch with our sales team. - - - If your contract includes a limit for the number of unique handles that can be used with Engagement API.  The internal X system will keep track of the number of Authenticated users owning Posts that are queried with the Engagement API.  Customers should also keep track of this unique number on the client side.  Currently, there is no usage API or UI to check the @handle usage for the Engagement API.  The system will not block overages if there are more @handles requested than what is contracted.  At the end of the billing month, the number of unique @handles queried is compared to the contracted amount and an overage will be charged in accordance with the contract terms. - - -Currently, there is no usage API or UI to check the @handle usage for the Engagement API.  The system will not block overages if there are more @handles requested than what is contracted.  At the end of the billing month, the number of unique @handles queried is compared to the contracted amount and an overage will be charged in accordance with the contract terms. - -**The `engagements` metadata field returned in the payload is not equal to the sum of all the various engagement metric totals. Why is this the case?** - -This is to be expected. The `engagements` metadata field may not always correlate with the sum of all individual engagement metrics returned by the API. This is because the `engagements` metadata field may include additional engagements that do not have specific metrics broken out in the payload. Said another way, adding all of the various engagement metric totals together may not equal the value you are seeing in the `engagements` metric field that is returned to you in the payload. - -You can think of the `engagements` metadata field as any click or interaction made on the Post. -  - -**The `url_clicks` field in the payload response is returning a number, when in fact the Post does not have a URL. How is this possible?** - -This may be because a Post that contains something like a hashtag (that creates a link to another page) will count as a URL click if it is clicked on by a user. -  - - -There are various reasons why you might not be able to retrieve engagement data for a specific Post, including: - -* The Post ID or IDs you have requested are not available based on the authentication token you are using to retrieve data on behalf of a third party. -* The Post ID or IDs you have requested specific to the /totals endpoint are not 90 days or newer and are thus not available for returning the impressions or engagement metrics. -* The Post ID or IDs you have requested are no longer available, usually indicating that they have been deleted or are no longer publicly available for another reason. - -Please review the different [error messages](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#error-messages) that you will likely receive in any of the above cases. - - -You can use the `x-per-minute-limit` and `x-per-minute-remaining` information returned by the response header when you make a request to the Engagement API to monitor your consumption. - -`x-per-minute-limit` tells you what your allowance is and `x-per-minute-remaining` tells you how many calls you have left. - - - - -### Error troubleshooting guide - - - - Please make sure to review our [guidelines on authenticating](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#authentication) with the Engagement API. - - -```bash -[ - Your account could not be authenticated. Reason: Unknown Authorization Type; -] -``` -Make sure not to use any access tokens or secrets when you try and authenticate with the /totals endpoint. This is because if you do include these tokens, and are attempting to pull content from a Post not associated with these tokens, you will likely receive an error such as: -```bash -[ - Forbidden to access tweets: 1054424731825229824; -] -``` - - -### Still can't find what you're looking for? - - -Please reach out to technical support and we will respond to you promptly. - - - -## API reference - -### **POST insights/engagement** - - -#### **Methods** - -| Method | Description | -| :--- | :--- | -| [POST /insights/engagement/totals](#Totals) | Retrieve total impressions and engagements for a collection of Tweets. | -| [POST /insights/engagement/historical](#Historical) | Retrieve impressions and engagements for a collection of Tweets for a period up to 4 weeks in duration, back to September 1, 2014. | -| [POST /insights/engagement/28hr](#api-28hr) | Retrieve impressions and engagements for a collection of Tweets for the past 28 hours. | - -#### **Authentication** - -The Engagement API requires the use of HTTPS and supports the use of both User Context and Application-Only OAuth. Most requests to the Engagement API require the use of 3-Legged OAuth (A specific version of User Context), meaning that you use the consumer key and secret of the app that has been registered and approved for Engagement API access by your Twitter account manager, as well as the Tweet owners' access token and access token secret to call the endpoint. The following requests require this type of OAuth: - -* Any request to /totals to obtain Impressions and Engagements metric types, which are limited to owned Tweets -* Any request to /28hr -* Any request to /historical - -Some requests to the Engagement API can be performed using Application-Only OAuth, meaning that you just need to provide your consumer key and secret, or a bearer token. The following request can be performed with this type of OAuth: - -* Any request to /totals to obtain Favorites, Replies, Retweets, or Video Views metric types, which can be retrieved for any Tweet - -For any request, you will need to set up a Twitter app and corresponding API key using the app management console available at [developer.x.com](https://developer.x.com/en/portal/dashboard). - -Please note - You can view and edit your existing [Twitter apps](/resources/fundamentals/developer-apps) via the [Twitter app dashboard](https://developer.x.com/en/apps) if you are logged into your Twitter account on developer.x.com. - -Once you have set up your app, the app ID will need to be approved by your account representative in order for your app to make requests to the Engagement API. Access tokens must be used to represent the “current user”, and requests made on behalf of a separate user must be signed with a valid token. Ensure that you’re [encoding reserved characters](https://tools.ietf.org/html/rfc3986) appropriately within URLs and POST bodies before preparing OAuth signature base strings. - -For more information on how to get started with OAuth, please visit the following links: - -* [OAuth Overview](/resources/fundamentals/authentication) -* [Using 3 Legged OAuth, also known as User Context](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) -* [Using Application-Only OAuth](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only) - -#### **POST /insights/engagement/totals** - -The totals endpoint provides the ability to retrieve current total impressions and engagements for a collection of up to 250 Tweets at a time. - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | `https://data-api.x.com/insights/engagement/totals` | -| **Content Type** | `application/json` | -| **Compression** | Gzip. To make a request using Gzip compression, send an Accept-Encoding header in the connection request.
The header should look like the following:

`Accept-Encoding: gzip` | -| **POST Format** | Requests can be sent as a POST request where the body is a JSON object containing a collection of Tweet IDs and a desired grouping. The POST is formatted as an array with a `tweets`, `engagements`, and `groupings` object. Each request can have a maximum of 250 Tweet IDs.

An example POST body looks like:


\{
"tweet_ids": \[
"Tweet ID 1",
"Tweet ID 2",
"Tweet ID 3"
\],
"engagement_types": \[
"impressions",
"engagements",
"favorites",
"quote_tweets"
\],
"groupings": \{
"grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
}
} | -| **Tweet IDs** | An array that includes the Tweet IDs for the Tweets to be queried for engagement data. Please note that you are only able to request data for Tweets that were created by the authenticating @handle. Up to 250 Tweets may be included per request, and Tweet IDs must be represented as strings. | -| **Engagement Types** | An array that includes the types of engagement metrics to be queried. The Totals endpoint supports only the following engagement types: `impressions`, `engagements`, `favorites`, `retweets`, `quote_tweets`, `replies`, `video_views`.
The `/totals` endpoint supports the ability to retrieve `impressions` and `engagements` for Tweets created within the last 90 days, and `favorites`, `retweets`, `quote_tweets`, `replies`, and `video_views` for any Tweet. | -| **Groupings** | Results from the Engagement API can be returned in different groups to best fit your needs. You can include a maximum of 3 groupings per request.

For each grouping, you may define a custom grouping name to make it easier to refer to this grouping type in your application.

Once you have defined a grouping name, you can choose to group `tweet.id` and/or `engagement.type`.

Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. An example grouping that will show metrics separated by Tweet ID and metric type looks like:


"groupings": \{
"my grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
} | -| **POST Size Limit** | Requests can be made for a maximum of 250 Tweet IDs at a time. | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | You will be rate limited by minute, as specified in your contract according to your level of access. | -| **Example Request (public metrics)** | curl --request POST
--url https://data-api.x.com/insights/engagement/totals
--header 'accept-encoding: gzip'
--header 'authorization: Bearer '
--header 'content-type: application/json'
--data '\{
"tweet_ids": \[
"1070059276213702656","1021817816134156288","1067094924124872705"
\],
"engagement_types": \[
"favorites","retweets","replies","quote\_tweets","video\_views"
\],
"groupings": \{
"perTweetMetricsUnowned": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
}
}
--verbose
--compressed | -| **Example Request** | curl --request POST
--url https://data-api.x.com/insights/engagement/totals
--header 'accept-encoding: gzip'
--header 'authorization: OAuth oauth\_consumer\_key="consumer-key-for-app",oauth\_nonce="generated-nonce",oauth\_signature="generated-signature",oauth\_signature\_method="HMAC-SHA1", oauth\_timestamp="generated-timestamp",oauth\_token="access-token-for-authed-user", oauth_version="1.0"'
--header 'content-type: application/json'
--data '\{
"tweet_ids": \[
"1060976163948904448","1045709644067471360"
\],
"engagement_types": \[
"favorites","replies","retweets","video_views","impressions","engagements"
\],
"groupings": \{
"perTweetMetricsOwned": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
}
}'
--verbose
--compressed | -| **Example Response (public metrics)** | \{
"perTweetMetricsUnowned": \{
"1021817816134156288": \{
"favorites": "530",
"quote_tweets": "79",
"replies": "147",
"retweets": "323",
"video_views": "0"
},
"1067094924124872705": \{
"favorites": "1360",
"quote_tweets": "29",
"replies": "56",
"retweets": "178",
"video_views": "5754512"
},
"1070059276213702656": \{
"favorites": "69",
"quote_tweets": "5",
"replies": "7",
"retweets": "26",
"video_views": "0"
}
}
} | -| **Example Response** | \{
"perTweetMetricsOwned": \{
"1045709644067471360": \{
"engagements": "2",
"favorites": "0",
"impressions": "47",
"replies": "0",
"retweets": "8",
"quote_tweets": "5",
"video_views": "0"
},
"1060976163948904448": \{
"engagements": "4",
"favorites": "0",
"impressions": "148",
"replies": "1",
"retweets": "9",
"quote_tweets": "2",
"video_views": "0"
}
}
} | -| **Unavailable Tweet IDs** | For queries that include Tweet IDs that have been made unavailable (e.g., have been deleted), appropriate data will be returned for all available Tweet IDs, and unavailable Tweet IDs will be referenced in an array called `unavailable_tweet_ids`. For example:

\{
"start": "2015-11-17T22:00:00Z",
"end": "2015-11-19T02:00:00Z",
"unavailable\_tweet\_ids": \[
"323456789"
\],
"group1": \{
"423456789": \{
"favorites": "67",
"replies": "8",
"retweets": "26",
"quote_tweets": "2"
}
}
} | - -#### **POST /insights/engagement/28hr** - -The 28 hour endpoint provides the ability to retrieve impressions and engagements for a collection of up to 25 Tweets for the past 28 hours. The 28 hour endpoint also provides the ability to request metrics for all supported individual metrics. For the full list of supported metrics see [Metric Availability](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#EngagementTypes). - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | `https://data-api.x.com/insights/engagement/28hr` | -| **Content Type** | `application/json` | -| **Compression** | Gzip. To make a request using Gzip compression, send an Accept-Encoding header in the connection request.
The header should look like the following:

`Accept-Encoding: gzip` | -| **POST Format** | Requests can be sent as a POST request where the body is a JSON object containing a collection of Tweet IDs and a desired grouping. The POST is formatted as an array with a `tweets`, `engagements`, and `groupings` object. Each request can have a maximum of 25 Tweet IDs.

An example POST body looks like:


\{
"tweet_ids": \[
"Tweet ID 1",
"Tweet ID 2",
"Tweet ID 3"
\],
"engagement_types": \[
"impressions",
"engagements",
"url_clicks",
"detail_expands"
\],
"groupings": \{
"grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.hour"
\]
}
}
} | -| **Tweet IDs** | An array that includes the Tweet IDs for the Tweets to be queried for engagement data. Please note that you are only able to requests data for Tweets that were created by the authenticating @handle. The 28 hour endpoint supports up to a maximum of 25 Tweets per request, and Tweet IDs must be represented as strings. | -| **Engagement Types** | An array the types of engagement metrics to be queried.

For the 28 hour endpoint, `impressions`, `engagements`, and all individual engagement types are supported metrics. For the full list of supported engagement metrics see [Engagement Data](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#AvailableData). | -| **Groupings** | Results from the Engagement API can be returned in different groups to best fit your needs. You can include a maximum of 3 groupings per request.

For each grouping, you may define a custom grouping name to make it easier to refer to this grouping type in your application. Once you have defined a grouping name, you can choose to group by one or more of the following values:
`tweet.id`
`engagement.type`
`engagement.day`
`engagement.hour`
Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. An example grouping that will show metrics separated by Tweet ID, metric type, and looks like:

"groupings": \{
"my grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day"
\]
}
}


Groupings that have 4 `group_by` items are only valid if they use one of the following two orders. Requests that have 4 `group_by` items in a single grouping that are not one of the following will return an error. Additionally, only one grouping with 4 `group_by` items will be allowed per request.

"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day",
"engagement.hour"
\]

"group_by": \[
"engagement.type",
"tweet.id",
"engagement.day",
"engagement.hour"
\] | -| **POST Size Limit** | Requests can be made for a maximum of 25 Tweet IDs at a time. | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | You will be rate limited by minute, as specified in your contract according to your level of access. | -| **Example Request** | curl -X POST "https://data-api.x.com/insights/engagement/28hr"
-H 'Accept-Encoding: gzip'
-H 'Authorization OAuth oauth\_consumer\_key="consumer-key-for-app",oauth\_nonce="generated-nonce",oauth\_signature="generated-signature",oauth\_signature\_method="HMAC-SHA1", oauth\_timestamp="generated-timestamp",oauth\_token="access-token-for-authed-user", oauth_version="1.0"'
-d '\{
"tweet_ids": \[
"123456789"
\],
"engagement_types": \[
"impressions",
"engagements"
\],
"groupings": \{
"hourly-time-series": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day",
"engagement.hour"
\]
}
}
}' | -| **Example Response** | \{
"start": "2015-09-14T17:00:00Z",
"end": "2015-09-15T22:00:00Z",
"hourly-time-series": \{
"123456789": \{
"impressions": \{
"2015-09-14": \{
"17": "551",
"18": "412",
"19": "371",
"20": "280",
"21": "100",
"22": "19",
"23": "6"
},
"2015-09-15": \{
"00": "5",
"01": "2",
"02": "7",
"03": "3",
"04": "1",
"05": "0",
"06": "0",
"07": "0",
"08": "0",
"09": "0",
"10": "0",
"11": "0",
"12": "0",
"13": "0",
"14": "0",
"15": "0",
"16": "0",
"17": "0",
"18": "0",
"19": "0",
"20": "0",
"21": "0"
}
},
"engagements": \{
"2015-09-14": \{
"17": "0",
"18": "0",
"19": "0",
"20": "0",
"21": "0",
"22": "0",
"23": "0"
},
"2015-09-15": \{
"00": "0",
"01": "0",
"02": "0",
"03": "0",
"04": "0",
"05": "0",
"06": "0",
"07": "0",
"08": "0",
"09": "0",
"10": "0",
"11": "0",
"12": "0",
"13": "0",
"14": "0",
"15": "0",
"16": "0",
"17": "0",
"18": "0",
"19": "0",
"20": "0",
"21": "0"
}
}
}
}
} | -| **Unavailable Tweet IDs** | For queries that include Tweet IDs that have been made unavailable (e.g., have been deleted), appropriate data will be returned for all available Tweet IDs, and unavailable Tweet IDs will be referenced in an array called `unavailable_tweet_ids`. For example:

\{
"start": "2015-11-17T22:00:00Z",
"end": "2015-11-19T02:00:00Z",
"unavailable\_tweet\_ids": \[
"323456789"
\],
"group1": \{
"423456789": \{
"favorites": "67",
"replies": "8",
"retweets": 26
}
}
} | - -#### **POST /insights/engagement/historical** - -The historical endpoint provides the ability to retrieve impressions and engagements for a collection of up to 25 Tweets for any period up to 4 weeks in duration. Currently, data older than September 1, 2014 cannot be requested from the API. The historical endpoint also provides the ability to request metrics for all supported individual metrics. For the full list of supported metrics see [Metric Availability](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#EngagementTypes). - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | `https://data-api.x.com/insights/engagement/historical` | -| **Content Type** | `application/json` | -| **Compression** | Gzip. To make a request using Gzip compression, send an Accept-Encoding header in the connection request.
The header should look like the following:

`Accept-Encoding: gzip` | -| **POST Format** | Requests can be sent as a POST request where the body is a JSON object containing a collection of Tweet IDs and a desired grouping. The POST is formatted as an array with a `tweets`, `engagements`, and `groupings` object. Each request can have a maximum of 25 Tweet IDs. Each request can be specified with a custom Start and End date up to four weeks in duration.


\{
"tweet_ids": \[
"Tweet ID 1",
"Tweet ID 2",
"Tweet ID 3"
\],
"engagement_types": \[
"impressions",
"engagements",
"url_clicks",
"detail_expands"
\],
"groupings": \{
"grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.hour"
\]
}
}
} | -| **Start and End Date** | A custom start and end date can be specified with the `start` and `end` values as part of the request. You must specify a start and end date that are not longer than 4 weeks in duration. The oldest possible start date at this time is September 1, 2014. End dates in the future are not supported. If no Start and End date are supplied, the API will default to the immediately previous 4 weeks.

The lowest granularity that data can be returned from the Engagement API is by hour. For any requests made with Start or End values that do not fall directly on an hourly boundary, requests will default to the nearest inclusive hour. For instance, a request with "start":"2015-07-01T12:24:00Z" and "end":"2015-07-10T08:37:00Z" will default to "start":"2015-07-01T12:00:00Z","end":"2015-07-10T09:00:00Z". | -| **Tweet IDs** | An array that includes the Tweet IDs for the Tweets to be queried for engagement data. Please note that you are only able to requests data for Tweets that were created by the authenticating @handle. The 4 week historical endpoint supports up to a maximum of 25 Tweets per request, and Tweet IDs must be represented as strings. | -| **Engagement Types** | n array that includes the types of engagement metrics to be queried.

For the 4 week historical endpoint, `impressions`, `engagements`, and all individual engagement types are supported metrics. For the full list of supported engagement metrics see [Engagement Data](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#AvailableData).

\*\*Note:\*\*Currently there are three metrics that will display as zero for queries made before September 15, 2015: `favorites`, `replies`, and `retweets`. | -| **Groupings** | Results from the Engagement API can be returned in different groups to best fit your needs. You can include a maximum of 3 groupings per request.

For each grouping, you may define a custom grouping name to make it easier to refer to this grouping type in your application. Once you have defined a grouping name, you can choose to group by one or more of the following values:
`tweet.id`
`engagement.type`
`engagement.day`
`engagement.hour`
Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. An example grouping that will show metrics separated by Tweet ID, metric type, and looks like:

"groupings": \{
"my grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day"
\]
}
}


Groupings that have 4 `group_by` items are only valid if they use one of the following two orders. Requests that have 4 `group_by` items in a single grouping that are not one of the following will return an error. Additionally, only one grouping with 4 `group_by` items will be allowed per request.

"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day",
"engagement.hour"
\]

"group_by": \[
"engagement.type",
"tweet.id",
"engagement.day",
"engagement.hour"
\] | -| **POST Size Limit** | Requests can be made for a maximum of 25 Tweet IDs at a time. | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | You will be rate limited by minute, as specified in your contract according to your level of access. | -| **Example Request** | curl -XPOST "https://data-api.x.com/insights/engagement/historical"
-H 'Accept-Encoding: gzip'
-H 'Authorization OAuth oauth\_consumer\_key="consumer-key-for-app",oauth\_nonce="generated-nonce",oauth\_signature="generated-signature",oauth\_signature\_method="HMAC-SHA1", oauth\_timestamp="generated-timestamp",oauth\_token="access-token-for-authed-user", oauth_version="1.0"'
-d '\{
"start": "2015-08-01",
"end": "2015-08-15",
"tweet_ids": \[
"123456789",
"223456789",
"323456789"
\],
"engagement_types": \[
"impressions",
"engagements",
"url_clicks",
"detail_expands"
\],
"groupings": \{
"types-by-tweet-id": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
}
}' | -| **Example Response** | \{
"start": "2015-08-01T00:00:00Z",
"end": "2015-08-15T00:00:00Z",
"types-by-tweet-id": \{
"123456789": \{
"impressions": "0",
"engagements": "0",
"url_clicks": "0",
"detail_expands": "0"
},
"223456789": \{
"impressions": "788",
"engagements": "134",
"url_clicks": "30",
"detail_expands": "1323"
},
"323456789": \{
"impressions": "4",
"engagements": "0",
"url_clicks": "2",
"detail_expands": "0"
}
}
} | -| **Unavailable Tweet IDs** | For queries that include Tweet IDs that have been made unavailable (e.g., have been deleted), appropriate data will be returned for all available Tweet IDs, and unavailable Tweet IDs will be referenced in an array called `unavailable_tweet_ids`. For example:

\{
"start": "2015-11-17T22:00:00Z",
"end": "2015-11-19T02:27:50Z",
"unavailable\_tweet\_ids": \[
"323456789"
\],
"group1": \{
"423456789": \{
"favorites": "67",
"replies": "8",
"retweets": 26
}
}
} | - -#### **Response codes** - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful. | -| 400 | Bad Request | Generally, this response occurs due to the presence of invalid JSON in the request, or where the request failed to send any JSON payload. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Check your OAuth keys and tokens. | -| 404 | Not Found | The resource was not found at the URL to which the request was sent, likely because an incorrect URL was used. | -| 429 | Too Many Requests | Your app has exceeded the limit on API requests. | -| 500 | Internal Server Error | There was an error on Gnip's side. Retry your request using an exponential backoff pattern. | -| 502 | Proxy Error | There was an error on Gnip's side. Retry your request using an exponential backoff pattern. | -| 503 | Service Unavailable | There was an error on Gnip's side. Retry your request using an exponential backoff pattern. | - -#### **Error Messages** - -In various scenarios, the Engagement API will occur situation-specific error messages that your application should be equipped to deal with. The table below includes common examples of these error messages and how you should interpret them. Please note that in many cases the Engagement API will return partial results for available data with specific error messages as part of a 200 OK response with more information. - -| Error Message | Description | -| :--- | :--- | -| `"errors":["Your account could not be authenticated. Reason: Access token not found"]` | An error in the authentication component of the request. The “Reason” should provide information that is helpful to troubleshoot the error. In cases where you are not able to resolve, please send the full error, including the “Reason”, to our support team. | -| `"errors":["1 Tweet ID(s) are unavailable"],"unavailable_tweet_ids": ["TWEET_IDS"]` | The Tweet ID or IDs you have requested are no longer available, usually indicating that they have been deleted or are no longer publicly available for another reason. | -| `"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*]` | The Tweet ID or IDs you have requested specific to the /totals endpoint are not 90 days or newer and are thus not available for returning the impressions or engagements metrics. | -| `"errors":["Forbidden to access tweets: *TWEET_IDS*"]` | The Tweet ID or IDs you have requested are not available based on the authentication token you are using to retrieve data on behalf of a third party. | diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/firehouse.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/firehouse.mdx deleted file mode 100644 index 3784784d1..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/firehouse.mdx +++ /dev/null @@ -1,382 +0,0 @@ ---- -title: Compliance Firehose API -keywords: ["compliance firehose", "firehose API", "compliance API", "enterprise firehose", "compliance stream", "firehose"] ---- - ->**Please note** -> ->We have released a new compliance tool to X API v2 called [batch compliance](/x-api/compliance/batch-compliance). This new tool allows you to upload large datasets of Post or user IDs to retrieve their compliance status in order to determine what data requires action in order to bring your datasets into compliance. - ->In addtion, both the batch compliance and the compliance firehose have been updated to support Post edits. For the compliance firehose, a new 'tweet_edit' event was added. See the [Compliance Data Objects](/x-api/enterprise-gnip-2.0/fundamentals/firehouse#compliance-data-objects) documentation for more details. Learn more about how Edit Post metadata works on the [Edit Posts fundamentals](/x-api/fundamentals/edit-posts) page. - -## Overview - -`Enterprise` - -One of X's core values is to defend and respect the user’s voice. This includes respecting their expectations and intent when they delete, modify, or edit the content they choose to share on X. We believe that this is critically important to the long term health of one of the largest public, real-time information platforms in the world. X puts controls in the hands of its users, giving individuals the ability to control their own X experience. We believe that business consumers that receive X data have a responsibility to honor the expectations and intent of end users. - -For more information on the types of compliance events that are possible on the X platform, reference our article, [Honoring User Intent on X](/x-api/enterprise-gnip-2.0/fundamentals/firehouse#honoring-user-intent-on-twitter). - -Any developer or company consuming X data via an API holds an obligation to use all reasonable efforts to honor changes to user content. This obligation extends to user events such as deletions, modifications, and changes to sharing options (e.g., content becoming protected or withheld). This also includes when users edit their Posts. Please reference the specific language in the [Developer Policy](https://developer.x.com/en/developer-terms/policy) and/or your X Data Agreement to understand how this obligation affects your use of X data. - -X offers the following solutions that deliver information about these user compliance events and whether a specific Post or User is publicly available or not. A brief overview of the solutions and their general integration patterns is detailed below: - -#### GET statuses/lookup and GET users/lookup - -* Format: REST API’s See: [GET statuses/lookup](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/get-statuses-lookup) and [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup). -* These endpoints always return the latest version of any Post edits. All Post objects describing Posts created after the edit feature was introduced will include Post edit metadata. This is true even for Posts that were not edited.  -* For all Posts, requests for Posts more than 30 minutes after they were created will represent the final state of all Posts.  - -* Deliver availability information for specific Posts or Users as defined by the caller as part of the API request. -* May be used for ad-hoc spot-checking on the current availability state of a specific group of Posts / Users. -* Ideal for customers who need a way to check the current state of a specific Post or User at a given moment in time. -* These API’s provide a helpful mechanism that may be used by customers who need to check the availability of a piece of Content, for instance when: - 1. Displaying Posts - 2. Engaging with a Post(s) or User(s) in a 1:1 way - 3. Distributing X Content to a 3rd party through an allowed file download - 4. Storing Posts for extended periods of time - -#### Compliance Firehose (enterprise only) - -* Format: Streaming API See: [Compliance Firehose](/x-api/enterprise-gnip-2.0/fundamentals/firehouse#api-reference). -* Delivers realtime stream of [Compliance activities](/x-api/enterprise-gnip-2.0/fundamentals/firehouse#compliance-data-objects) on X. These activities include when Posts are edited.  -* May be used to maintain compliance state across a set of stored data as new compliance events happen on the platform. -* Ideal for customers consuming and storing large quantities of X data for extended periods of time. - -## Guides - -### **Compliance Best Practices** - -#### **Recommendations & Best Practices** - -* **Build Data Storage Schemas That Store Numeric Post ID and User ID**: User messages require action to be taken on all Posts from that User. Therefore, since all compliance messages are delivered only by numeric ID, it is important to design storage schemas that maintain the relationship between Post and User based on numeric IDs. Data consumers will need to monitor compliance events by both Post ID and User ID and be able to update the local data store appropriately. - -* **Build Schemas That Address All Compliance Statuses**: Depending on how compliance activities will be addressed in various applications, it may be required to add other metadata to the data store. For instance, data consumers may decide to add metadata to an existing database to facilitate restricting the display of content in countries affected by a status\_withheld message. - -* **Handling Retweet Deletes**: Retweets are a special kind of Post where the original message is nested in an object within the Retweet. In this case, there are two Post IDs referenced in a Retweet – the ID for the Retweet, and the ID for the original message (included in the nested object). When an original message is deleted, a Post delete message is issued for the original ID. Post deletion events typically trigger delete events for all Retweets. However, in some cases not all are sent and client systems should be tolerant of incomplete Retweet deletions. The deletion of the original ID should be sufficient to delete all subsequent Retweets. It is a best practice to reference the original Post ID when storing Retweets, and deleting all referenced Retweets when receiving Post delete events. - -### Compliance Data Objects - -#### **Compliance Firehose API** - -Possible types of compliance events will include Post (or “status”) events and User events, for which there are multiple types described below.   - -Please note: - -* Read more about User statuses [here](https://support.x.com/articles/14016) and our developer policy around deleted Posts [here](https://dev.x.com/overview/terms/policy#3.Update_Respect_Users_Control_and_Privacy). -* The Compliance Firehose has been updated to provide 'tweet_edit' events.  -* Several User delete, protect and suspend events are not necessarily permanent and can toggle between states infinitely. These include: user\_delete,user\_undelete, user\_protect, user\_unprotect and user\_suspend, user\_unsuspend. -* User\_deletes are followed by status\_deletes 30 days later only if the user has not selected to user\_undelete their account. It is possible that a user\_delete is reversed by the user and deletes for all of their Posts 30 days later do not occur. -* User\_suspend is an action that remains true unless the user is subject to an user\_unsuspend event. These are not subject to any changes on a 30 day time period. - -Refer to the ‘Recommended Action’ column to understand how to process each type of event in order to respect the privacy and intent of the end user. - - -| Original Message Type | Object | Permanent (Yes/No) | Recommended Action | -| :--- | :--- | :--- | :--- | -| delete | Status | Yes | Delete associated Post. | -| status_withheld | Status | Yes | Suppress associated Post in specific countries listed in the status_withheld message. | -| drop | Status | No | Remove the Post from public view. | -| undrop | Status | No | Status may be displayed again and treated as public. | -| tweet_edit | Status | Yes | Honor and, where relevant, display the new edit. | -| user_delete | User | No | Suppress or delete all Posts by associated user. | -| user_undelete | User | No | All Posts by associated user may be displayed again and treated as public. | -| user_protect | User | No | Suppress or delete all Posts by associated user. | -| user_unprotect | User | No | All Posts by associated user may be displayed again and treated as public. | -| user_suspend | User | No | Suppress or delete all Posts by associated user. | -| user_unsuspend | User | No | All Posts by associated user may be displayed again and treated as public. | -| scrub_geo | User | Yes | Delete all geodata provided by X for all Posts by the user prior to the specified Post in the scrub_geomessage. Note that subsequent Posts by a user may contain geodata that may be used. | -| user_withheld | User | Yes | Suppress Posts by associated user in specific countries listed in the user_withheld message. | -| delete | Favorite | Yes | Delete associated like/favorite. | - -#### **Payload examples** - -See the payload examples below for each compliance event described in the table above. - -**Post edit** - -```json -{"tweet_edit": - { - "id": "1557445923210514432" - "initial_tweet_id": "1557433858676740098", - "edit_tweet_ids": ["1557433858676740098", "1557445923210514432"], - "timestamp_ms": "1660155761384" - } - } -``` - -##### Post delete - -```json -{ - "delete": { - "status": { - "id": 601430178305220600, - "id_str": "601430178305220608", - "user_id": 3198576760, - "user_id_str": "3198576760" - }, - "timestamp_ms": "1432228155593" - } -} -``` - -##### Post withheld - -```json -{ - "status_withheld": { - "status": { - "id": 601430178305220600, - "id_str": "601430178305220608", - "user_id": 3198576760, - "user_id_str": "3198576760" - }, - "withheld_in_countries": [ - "XY" - ], - "timestamp_ms": "1432228155593" - } -} -``` - - -##### Drop - -```json -{ - "drop": { - "status": { - "id": 601430178305220600, - "id_str": "601430178305220600", - "user_id": 3198576760, - "user_id_str": "3198576760" - }, - "timestamp_ms": "1432228155593" - } -} -``` - - -##### Undrop - -```json -{ - "undrop": { - "status": { - "id": 601430178305220600, - "id_str": "601430178305220600", - "user_id": 3198576760, - "user_id_str": "3198576760" - }, - "timestamp_ms": "1432228155593" - } -} -``` - - -#### Scrub geo -```json -{ - "scrub_geo": { - "user_id": 519761961, - "up_to_status_id": 411552403083628540, - "up_to_status_id_str": "411552403083628544", - "user_id_str": "519761961", - "timestamp_ms": "1432228180345" - } -} -``` - - -##### User delete - -```json -{ - "user_delete": { - "id": 771136850, - "timestamp_ms": "1432228153548" - } -} -``` - -##### User undelete -```json -{ - "user_undelete": { - "id": 796250066, - "timestamp_ms": "1432228149062" - } -} -``` - - -##### User withheld - -```json -{ - "user_withheld": { - "user": { - "id": 1375036644, - "id_str": "1375036644" - }, - "withheld_in_countries": [ - "XY" - ], - "timestampMs": "2014-08-27T23:49:41.839+00:00" - } -} -``` - -##### User protect - -```json -{ - "user_protect": { - "id": 3182003550, - "timestamp_ms": "1432228177137" - } -} -``` - - -##### User unprotect -```json -{ - "user_unprotect": { - "id": 2911076065, - "timestamp_ms": "1432228180113" - } -} -``` - -##### User suspend - -```json -{ - "user_suspend": { - "id": 3120539094, - "timestamp_ms": "1432228194217" - } -} -``` - - -##### User unsuspend -```json -{ - "user_unsuspend": { - "id": 3293130873, - "timestamp_ms": "1432228193828" - } -} -``` -### integrating Compliance Firehose - -The Compliance Firehose is a realtime streaming API that delivers compliance events that occur on the X platform. For an understanding of compliance events and how they are generated on X, please reference our article, [Honoring User Intent on X](/x-api/enterprise-gnip-2.0/fundamentals/firehouse#honoring-user-intent-on-twitter). - -It is important to note that Post and User events are delivered independently and that each should be processed independently (i.e. a Post delete doesn’t imply a User event, and vice versa.) Several User events are not necessarily permanent and can toggle between states infinitely. These include: user\_delete,user\_undelete, user\_protect, user\_unprotect and user\_suspend, user\_unsuspend. - -User\_deletes are followed by status\_deletes 30 days later only if the user has not selected to user\_undelete their account. It is possible that a user\_delete is reversed by the user and deletes for all of their Posts 30 days later do not occur. - -User\_suspend is an action that remains true unless the user is subject to an user\_unsuspend event. These are not subject to any changes on a 30 day time period. - -It is never suitable to display compliance events directly to users of your software or to otherwise incorporate them into your products or customer experiences. They are intended solely for maintaining compliance and honoring the actions of X users. - -#### **Integrating with the Compliance Firehose** - -To integrate the Compliance Firehose into your system, you will need to build an integration that can do the following: - -1. Establish a streaming connection to each streaming API partition of the Compliance Firehose -2. Handle high data volumes – de-couple stream ingestion from additional processing using asynchronous processes -3. Reconnect to the stream partitions automatically when disconnected for any reason -4. Process compliance events that are relevant to Post and User data you have stored in accordance with the guidance presented above - - -### Honoring user intent on Twitter - -We believe that respecting the privacy and intent of X users is critically important to the long term health of one of the largest public, real-time information platforms in the world. X puts privacy controls in the hands of its users, giving individuals the ability to control their own X experience. As business consumers of X data, we have a collective responsibility to honor the privacy and actions of end users in order to maintain this environment of trust and respect. - -There are a variety of things that can happen to Posts and User accounts that impact how they are displayed on the platform. The actions that affect privacy and intent are defined at both the Status (Post) and User levels. These actions include: - -#### User - -| Action | Description | -| :--- | :--- | -| Protect Account | A X user can protect or unprotect their account at any time. Protected accounts require manual user approval of every person who is allowed to view their account's Posts. 
For more information, see [About Public and Protected Posts](https://support.x.com/articles/14016-about-public-and-protected-tweets). | -| Delete Account | A X user can decide to delete their account and all associated status messages at any time. X retains the account information for 30 days after deletion in case the user decides to undelete and effectively reactivate their account. | -| Scrub Geo | A X user can remove all location data from past Posts at any time. This known as “scrub geo”. | -| Suspend Account | X retains the right to suspend accounts that are in violation of the X Rules or if an account is suspected to have been hacked or compromised. Account suspensions can only be reversed (unsuspend) by X. | -| Withhold Account | X retains the right to reactively withhold access to certain content in a specific country from time to time. A withheld account can only be made unwithheld by X. 
For more information, see [Country Withheld Content](https://support.x.com/articles/20169222-country-withheld-content). | - -#### Status - -| Action | Description | -| :--- | :--- | -| Delete Status | A X user can delete a status at any point in time. Deleted statuses cannot be reversed and are permanently deleted. | -| Withhold Status | X retains the right to reactively withhold access to certain content in a specific country from time to time. A withheld status can only be made unwithheld by X. 
For more information, see [Country Withheld Content](https://support.x.com/articles/20169222-country-withheld-content). | - -#### Keeping Track of User and Status Changes - -The state of a User or Status can change at any time due to one of the actions above, and this impacts how consumers of X data are expected to treat the availability and privacy of all associated content. When these actions happen, a corresponding compliance message is sent that indicates that the state of a Status or User has changed. - -## API Reference - -### **GET compliance/firehose** - -#### Methods - -| Method | Description | -| :--- | :--- | -| [GET /compliance/:stream](#Connect) | Connect to the Data Stream | - -#### Authentication - -All requests to the Compliance Firehose API must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. - -#### GET /compliance/:stream - -Establishes a persistent connection to the Compliance firehose data stream, through which the compliance events will be delivered. - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **Connection Type** | Keep-Alive | -| **URL** | Found on the stream's API Help page of your dashboard, and resembles the following structure:


[https://gnip-stream.x.com/stream/compliance/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition=1](https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1)

**Note:** The "partition" parameter is required. You will need to connect to all 8 partitions, each containing 12.5% of the total volume, to consume the full stream. | -| **Compression** | Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following:

Accept-Encoding: gzip | -| **Character Encoding** | UTF-8 | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | 10 requests per 60 seconds. | -| **Read Timeout** | Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds. | -| **Support for Tweet edits** | All Tweet edits trigger a "tweet_edit" Compliance event. See the [Compliance Data Objects](/x-api/enterprise-gnip-2.0/fundamentals/firehouse#compliance-data-objects) documentation for more details. | - -**Example Curl Request** - -The following example request is accomplished using cURL on the command line: - -```bash -curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1" -``` - -_Note:_ the above request is only connecting to `partition=1` of the Compliance firehose - you'll need to connect to all 8 partitions to consume the entirety of this stream. - -#### Response Codes - -The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect. - -| Status | Text | Definition | -| :--- | :--- | :--- | -| 200 | Success | The connection was successfully opened, and new activities will be sent through as they arrive. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 406 | Not Acceptable | Generally, this occurs where your client fails to properly include the headers to accept gzip encoding from the stream, but can occur in other circumstances as well. Will contain a JSON message similar to "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end." | -| 429 | Rate Limited | Your app has exceeded the limit on connection requests. | -| 503 | Service Unavailable | Twitter server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support. | - -#### Other Recommendations & Best practices - -* **Build Data Storage Schemas That Store Numeric Tweet ID and User ID**: User messages require action to be taken on all Tweets from that User. Therefore, since all compliance messages are delivered only by numeric ID, it is important to design storage schemas that maintain the relationship between Tweet and User based on numeric IDs. Data consumers will need to monitor compliance events by both Tweet ID and User ID and be able to update the local data store appropriately. - -* **Build Schemas That Address All Compliance Statuses**: Depending on how compliance activities will be addressed in various applications, it may be required to add other metadata to the data store. For instance, data consumers may decide to add metadata to an existing database to facilitate restricting the display of content in countries affected by a status_withheld message. - -* **Handling Retweet Deletes**: Retweets are a special kind of Tweet where the original message is nested in an object within the Retweet. In this case, there are two Tweet IDs referenced in a Retweet -- the ID for the Retweet, and the ID for the original message (included in the nested object). When an original message is deleted, a Tweet delete message is issued for the original ID. Subsequent delete messages are NOT issued for all of the Retweets. The deletion of the original ID should be sufficient to delete all subsequent Retweets. diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/overview.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/overview.mdx deleted file mode 100644 index 6b55b7a83..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/overview.mdx +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Gnip console -keywords: ["GNIP console", "enterprise console", "GNIP", "enterprise API", "GNIP API", "enterprise data", "GNIP platform"] ---- -## Overview - ->The enterprise console (at console.gnip.com) is available to enterprise data customers with contracted enterprise API access. If you are not currently an enterprise data customer but would like more information, you can learn more about [enterprise data](https://developer.x.com/en/products/x-api/enterprise) here. - -This is an overview of X's enterprise console dashboard. The sections that are covered pertain to each specific area of the console for product details, usage, and general account management. If you have any questions regarding your specific account, please contact your designated account manager, or review our [technical documentation for enterprise products](/x-api/enterprise-gnip-2.0/enterprise-gnip). - -As part of the enterprise trial and onboarding process with your account manager, enterprise customers will receive a login to [console.gnip.com](http://console.gnip.com), which is the user interface where enterprise product access can be reviewed and configured. Initial access to the console for customer admin is set up by X as part of the enterprise onboarding process, and admins can then add additional users. The enterprise console allows you to manage and access more details related to your enterprise products.  - -The following video provides an overview of the various portions of the console.gnip.com dashboard.  - -**Disclaimer: Please note that some of the features shown in the video, including certain stream enrichments and non-X data source products, may no longer be available.** - - - -## Products tab - -Upon logging into your account at [console.gnip.com](http://console.gnip.com), you will land on the products tab of the dashboard.  This page includes an overview of the enterprise products currently available on your account. - -For products using streaming delivery like PowerTrack or Decahose, this page lists the product name, and stream label,  the number of current active connections, the number of rules currently active for each (where applicable), and the raw count of activities (for example, Posts) delivered in the most recent 24 hours. - -For products with REST delivery, like Search API, this page lists the product name,labels (also shown as "streams"), current activities (for example, Posts) returned through these endpoints, and a few different request counts per endpoint. - -Note that the [Usage API](/x-api/enterprise-gnip-2.0/fundamentals/usage) delivers much of this data programatically. - -Specific details per stream are available by clicking the name, or the settings button. - - - - - -### Overview - -Clicking on one of the streams in the main dashboard will take you to an overview page for that stream. - -For streaming delivery products, this page includes the following: - -1. A volume chart of the number of activities being delivered to you through each specific stream connection  - -2. Details (connection ID and IP address) on currently active connections on the stream  - -3. A log of recent connection, disconnection, and rule-update events for your stream - - -Note that the scale of the chart may be adjusted with the links in the top-right corner. The visibility of individual connections and disconnections can be toggled by clicking the appropriate key in the legend directly below the chart. - - - - - -### Connections - -The Connections page provides details on recent connection events on your stream. This includes the start and end times for each connection (in 24 hour UTC), the duration of each connection, the IP of the server that made the connection, a unique connection ID for reference purposes, and the current connection status. The status corresponds to the most recent event for the specified connection – i.e. Client Connected, or a disconnect, with the type of disconnect specified.   For more details on connection debugging, visit the [disconnections explained guide](/x-api/enterprise-gnip-2.0/powertrack-api#integrating-with-powertrack). - - - - - -### API Help - -The API Help page provides the API endpoint URLs for your stream, as well as the Rules API endpoint for the stream, where applicable. In addition, it includes sample curl commands and instructions on how to connect to the stream endpoint, and how to programmatically add, delete, and list rules from your stream's Rules API endpoint. - - - - - -### Rules - -The Rules tab is available for PowerTrack streams, and provides a quick way to get started by manually entering plain text rules via a user interface. Note that the interface only supports adding up to 1000 rules via this manual method, and should be only used for initial testing. We recommend managing your rules programmatically via the [Rules API](/x-api/enterprise-gnip-2.0/powertrack-api#api-reference-index) in any production setting. - - - - - -### Settings - -The Settings tab allows you to switch the output format of the data in your stream, where multiple format options are supported. To switch the format, just use the radio buttons indicating the different options. The change will take effect upon reconnecting to the stream.  Note that updating this setting will take place immediately on the next request or connection and may break your parser with the new format.  - -**Please note:** The recommended setting for getting the most data is "Leave data in the original format" which will return data in the enriched native format [here](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#post-object).  Activity streams format is described [here](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#activity-object). - - - - - -## Usage tab - -The Usage Tab provides insight into your use of your streams over various time periods. For programmatic access to usage information, see the [Usage API](/x-api/enterprise-gnip-2.0/fundamentals/usage). - -### Monthly - -The Monthly Usage page displays your stream usage broken down by product. For example, coverage products (for example, PowerTrack, Historical PowerTrack, and PowerTrack Replay) for a given data source will be grouped together to provide separate data, as well as a combined roll-up count. The counts include a current month-to-date, estimated end-of-month (based on this month’s usage so far, and remaining time in the month), and the previous two months’ counts. - -Notably, these counts are deduplicated for each product and stream. If you received the same Post through multiple connections to the same PowerTrack stream, that Post will be counted once for these purposes. Counts will be updated every 24 hours at 00:00 UTC. - -### Daily - -The Daily Usage page provides daily deduplicated counts for each day in the current month, broken down by product. Counts are updated every 24 hours at 00:00 UTC. - -### Rules - -Rule limits are based on your contracted PowerTrack rule package and are applied across all streams of a given "type". Counts are updated whenever a new rule is added or deleted. - -## Account tab - -### My Profile - -View details about your individual user profile, and change your password here. Additionally, you may configure account usage threshold notices specific to your account.  API status notices are available through the status page at https://api.twitterstat.us. - -### Account Settings - -You may add, remove, and edit users, and configure email notifications for individual users and usage threshold alerts. - - - -Please note that there are three types of users – Account Admin, User, and Email Only.   - -* Account admins are allowed to create/delete/edit other users, and can use basic authentication with username (email) and password to connect to the enterprise APIs - -* Users cannot create or modify other users, but can use basic authentication with username (email) and password to connect to the enterprise APIs - -* Email Only users do not have access to the dashboard, are not authorized to connect to the enterprise APIs  and only receive notifications, if they are configured to receive them in the Notifications section. - - -### Usage Thresholds - -Configure volume thresholds for your products. These will initiate email alerts for the users who have configured those notifications in their profiles, both for the warning threshold and critical threshold for each product. - - - -Please note that these thresholds are evaluated once per day at 19:30 (UTC), and are not evaluated in real-time. diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/rate-limits.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/rate-limits.mdx deleted file mode 100644 index 3f7fba756..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/rate-limits.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Rate limits: Enterprise" -keywords: ["enterprise rate limits", "GNIP rate limits", "enterprise API limits", "rate limits enterprise", "enterprise throttling"] ---- - -## Overview - - -Every day many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, limits are placed on the number of requests that can be made. These limits help us provide the reliable and scalable API that our developer community relies on.  - -The maximum number of requests that are allowed is based on a time interval, some specified period or window of time. If an endpoint has a rate limit of 900 requests/15-minutes, then up to 900 requests over any 15-minute interval is allowed.  - -### Enterprise rate limits per window - -| Product | Endpoint | Rate limit | -| :--- | :--- | :--- | -| PowerTrack API | Streaming endpoint | 60 requests per minute | -| Rules endpoint | 60 requests per minute aggregated across all /rules endpoints | -| Replay endpoint | 5 requests per 5 minutes | -| Historical PowerTrack API | | 60 Jobs can be created per (UTC) day. | -| | 30 Jobs can be created per hour. | -| | 2 Jobs can be estimating concurrently. | -| | 2 Jobs can be running concurrently. | -| Decahose API | | 10 requests per minute | -| Streaming likes API | | 10 requests per minute | -| Firehose API | | 10 requests per minute | -| Account Activity API | POST account_activity/webhooks | 15 requests per 15 minutes | -| GET account_activity/webhooks | 15 requests per 15 minutes | -| PUT account\_activity/webhooks/:webhook\_id | 15 requests per 15 minutes | -| POST account\_activity/webhooks/:webhook\_id/subscriptions/all | 500 requests per 15 minutes | -| GET account_activity/subscriptions/count | 15 requests per 15 minutes | -| GET account\_activity/webhooks/:webhook\_id/subscriptions/all | 500 requests per 15 minutes | -| GET account\_activity/webhooks/:webhook\_id/subscriptions/all/list | 50 requests per 15 minutes | -| DELETE account\_activity/webhooks/:webhook\_id | 15 requests per 15 minutes | -| DELETE /account\_activity/webhooks/:webhook\_id/subscriptions/:user_id/all.json | 500 requests per 15 minutes | -| Replay | 5 requests per 15 minutes | -| Search API | | Per minute rate limit will vary by contract | -| | 20 requests per second aggregated across either the 30 day data and counts endpoints, or across the full-archive data and counts endpoints | -| Engagement API | | Per minute rate limit will vary by contract | -| Compliance Firehose API | | 10 requests per minute | -| Usage API | | 2 requests per minute | diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/rules-filtering.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/rules-filtering.mdx deleted file mode 100644 index e34b33192..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/rules-filtering.mdx +++ /dev/null @@ -1,340 +0,0 @@ ---- -title: "Rules and filtering: Enterprise" -keywords: ["enterprise rules", "GNIP rules", "enterprise filtering", "PowerTrack rules", "enterprise queries", "filter rules enterprise"] ---- - -## Getting started with enterprise rules and queries - - -Products utilizing enterprise operators deliver social data to you based on filtering rules you set up. Rules are made up of one or more ‘clauses’, where a clause is a keyword, exact phrase, or one of the many enterprise operators. Before beginning to build rules with enterprise operators, be sure to review the syntax described below, look through the list of available operators, and understand the restrictions around building rules. You should also be sure to understand the nuances of how rules are evaluated logically, in the "[Order of operations](#orderofoperations)" section. - -Multiple clauses can be combined with both "and" and "or" logic. - -**Please note:** "And" logic is specified with a space between clauses, while or logic is specified with an upper-case `OR`.  - -Each rule can be up to 2,048 characters long with no limits on the number of positive clauses (things you want to match or filter on) and negative clauses (things you want to exclude and not match on). -  - -### Building rules and queries  - -**Keyword match** - -Keyword matches are similar to queries in a search interface. For example, the following enterprise operator rule would match activities with the term "social" in the text body. - -`social` - -**ANDing terms with white space** - -Adding another keyword is the same as adding another requirement for finding matches. For example, this rule would only match activities where both "social" and "media" were present in the text, in either order – _having a space between terms operates as boolean AND logic_. If you include an explicit AND in your rule, it will rejected by the rules endpoint. - -`social media` - -**ORing terms with upper-case OR** - -Many situations actually call for boolean OR logic, however. This is easily accomplished as well. _Note that the OR operator must be upper-case and a lower-case ‘or’ will be treated as a regular keyword._ - -`social OR data` - -**Negating terms** - -Still other scenarios might call for excluding results with certain keywords (a boolean NOT logic). For instance, activities with ‘happy’, but excluding any with ‘birthday’ in the text. - -`social -personality` - -**Grouping with parentheses** - -These types of logic can be combined using grouping with parentheses, and expanded to much more complex queries. - -`(social OR data) (academic OR research) -personality -information -university` - -This is just the beginning though – while the above examples rely simply on tokenized matching for keywords, enterprise products also offer operators to perform different types of matching on the text. - -**Exact match** - -`"social media research"` - -**Substring match** - -`contains:info` - -**Proximity match** - -`"social media research"~3` - - -Further, other operators allow you to filter on unique aspects of social data, besides just the text.  - -**The user who is posting a Post** - -`from:XDeveloeprs` - -**Geo-tagged Tweets within 10 miles of Pearl St. in Boulder, CO, United States** - -`point_radius:[-105.27346517 40.01924738 10.0mi]` - -**Putting it all together** - -These can be combined with text filters using the same types of logic described above. - -`(social OR data) (academic OR research OR "social media research") point_radius:[-105.27346517 40.01924738 10.0mi] lang:en -personality -information -university` - -### Boolean Syntax - -The examples in the previous section, utilized various types of boolean logic and grouping. See the table below for additional detail regarding the syntax and requirements for each. - -| | | | -| :--- | :--- | :--- | -| **Logic type** | **Operator syntax** | Description | -| AND | social data | Whitespace between two operators results in AND logic between them

Matches activities containing both keywords ("social", "data").

**Do not use AND explicitly in your rule. Only use whitespace. An explicit AND will be treated like a regular keyword.** | -| OR | social OR data | To OR together two operators, insert an all-caps OR, enclosed in whitespace between them

Matches activities with EITHER keyword ("social" OR "data")

Note that if you combine OR and AND functionality in a single rule, you should understand the order of operations described in our "[Order of operations](#OrderOfOperations)" section, and consider grouping non-negated operators together using parentheses as described below to ensure your rule behaves as expected.

You must use upper-case "OR" in your rule. Lower-case 'or' will be treated as a regular keyword. | -| NOT | social data
-apple -android -phone | Insert a `-` character immediately in front of the operator or group of operators.

The example rule shown matches activities containing keyword "social", but excludes those which contain the keyword "data."

Negated ORs are not allowed where the rule would request "everything in the firehose except the negation." For example, `apple OR -ipad` is invalid because it would match all activities except those mentioning "ipad". | -| Grouping | (social OR data) -XDeveloeprs -api | Parentheses around multiple operators create a functional "group".

Groups can be connected to clauses in the same manner as an individual clause via whitespace (AND) or ORs. However, note that it is a best practice to not group together negations by applying the negating - to the entire group. Instead, you should negate each individual operator, stringing them together via whitespace (AND). 

For example, instead of using -(iphone OR imac OR macbook), use the following: -iphone -imac -macbook

Grouping is especially important where a single rule combines AND and OR functionality, due to the order of operations used to evaluate the rule. See below for more details. | - -**Please note:** that operators may be either positive or negative. - -**Positive Operators** define what you want to **include** in the results. E.g. the `has:hashtags` operator says “I want activities containing hashtags.” - -**Negative Operators** define what you want to **exclude** from the results, and are created by using the Boolean NOT logic described above. For example, `-has:hashtags` says “Exclude any activities containing hashtagss, even if they otherwise match my rule.” - -Premum operator products have no restriction on the number of positive and negative clauses, subject to a maximum length of 2,048 characters. -  - -#### Order of Operations - -When combining AND and OR functionality in a single rule, the following order of operations will dictate how your rule is evaluated. - -1. Operators connected by AND logic are combined first -2. Then, operators connected with OR logic are applied - -**Example:** - -* `apple OR iphone ipad` would be evaluated as `apple OR (iphone ipad)` -* `ipad iphone OR android` would be evaluated as `(iphone ipad) OR android` - -To eliminate uncertainty and ensure that your rules are evaluated as intended, group terms together with parentheses where appropriate. For example: - -* `(apple OR iphone) ipad` -* `iphone (ipad OR android)` - -#### Punctuation, Diacritics, and Case Sensitivity - -If you specify a keyword or hashtag rule with character accents or diacritics for enterprise operators, it will match Post text honoring the diacritics (hashtags or keywords). Rule with a keyword `Diacr**í**tica` or hashtag `#cumplea**ñ**os` will match "Diacr**í**tica" or "#cumplea**ñ**os" but not "Diacritica" or "#cumpleanos" without the tilde **í** or **eñe**. - -Characters with accents or diacritics are treated the same as normal characters and are not treated as word boundaries. For example, a rule of cumplea**ñ**os would only match activities containing the word cumpleaños and would not match activities containing cumplea, cumplean, or os. - -All operators are evaluated in a case-insensitive manner. For example, the rule `Cat` will match all of the following: "cat", "CAT", "Cat". - -#### PowerTrack rule tags - -As described on our "[Matching rules](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#matching-rules)" page, each rule may be created with a tag. These tags have no effect on filtering, but can be used to create logical groupings of rules within your app. Each rule may have only one tag, with a maximum of 255 characters. Tags are included with the JSON formatted rule at the time of creation via the API, as described on our "Matching rules" page. - -#### Putting Rules in JSON Format - -In order to add or delete a rule from a stream via the API, the rules must utilize JSON format. Essentially, this requires putting each rule into the following structure: - -`{"value":"insert_rule_here"}` - -**Rules with double-quotes** - -If the rule contains double-quote characters (`“`) associated with exact-match or other operators, they must be escaped using a backslash to distinguish them from the structure of the JSON format. - -`"social data" @XDevelopers` - -The JSON formatted rule would be: - -`{"value":"\"social data\" @XDevelopers"}` - -**Rules with double-quote string literals** - -To include a double-quote character as a string literal within an exact-match, it must be double-escaped. For example, for a rule matching on the exact phrase "Toys “R” Us", including the double-quotes around "R", the plain-text representation of this would look like the following: - -`"Toys \"R\" Us"` - -Translating this to JSON format, you should use the following structure: - -`{"value":"\"Toys \\\"R\\\" Us\""}` - -**Rules with Tags** - -To include an optional tag with your rule, as described above, simply include an additional `tag` field with the rule value. - -`{"value":"\"social data\" @XDevelopers","tag":"RULE-TAG-01"}` - -**Formatting for API Requests** - -When adding or deleting rules from the stream via the API, multiple JSON formatted rules should be comma delimited, and wrapped in a JSON “rules” array, as shown below: - -`{"rules":[{"value":"from:XDevelopers"},{"value":"\social data\" @XDevelopers","tag":"RULE-TAG-01"}]}` - -#### Operators that match Quote Tweets - -When using the [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api) and Historical PowerTrack API, the operators below will match on content from both the original Post that was quoted and the new Quote Tweet. - -However, if you are using the [Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api), these operators will only match the contents of the Quote Tweet, and will not match on any content from the original Post that was quoted. - -* `Keywords` -* `Phrases` -* `Proximity` -* `#hashtags` -* `@mentions` -* `$cashtags` -* `url:` -* `url_contains:` -* `has:links` -* `has:mentions` -* `has:hashtags` -* `has:media` -* `has:symbols` -* `is:quote` -* `is:reply` - -## Enterprise operators - -Below are the operators available with PowerTrack and Historical PowerTrack. A subset of these are available with the 30-Day and Full-Archive search APIs. See [this table](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#operators-by-product) for a product-by-product list of available operators.  - -| Operator | Description | -|:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| keyword | Matches a keyword within the text body or URL of a Post. Keywords must start with either a digit (0-9) or any non-punctuation character.
Keyword matching is tokenized, meaning the keyword is matched against tokenized text of the Post body.
For strings with punctuation (e.g., "coca-cola"), use a quoted "exact phrase match".
_Example_: `(social OR pizza OR wildfire) -planet` | -| emoji | Matches an emoji within the body of a Post, using tokenized matching based on punctuation, symbol/emoji, and separator characters.
If an emoji has a variant, use quotes for exact matches.
_Example_: `(🍕 OR 💜 OR 🐢) -🤖` | -| "exact phrase match" | Matches an exact phrase within the body of a Post. Punctuation is treated as whitespace.
_Example_: `("social media" OR "developer.x.com" OR "wildfire911" OR "coca-cola") -"planet earth"` | -| # | Matches any Post with the specified hashtag. This is an exact match, meaning `#2016` will match posts with `#2016` but not `#2016election`.
_Example_: `(#social OR #pizza OR #2016election) -#planet` | -| @ | Matches any Post mentioning the specified username.
_Example_: `(@XDevelopers OR @api OR @twittereng) -@jack` | -| "keyword1 keyword2"~N | Proximity operator that matches a Post where keywords are within N tokens of each other.
Keywords in reverse order can be no more than N-2 tokens apart. N cannot be greater than 6.
_Example_: `"social media"~5 OR "API"~3` | -| contains: | Substring match for Posts with the specified substring in the body, regardless of tokenization.
Use double quotes for substrings with whitespace or punctuation.
_Example_: `(contains:social OR contains:"wikipedia.com") -contains:"buy now"` | -| from: | Matches any Post from a specific user by X numeric Account ID or username (excluding `@`).
_Example_: `(from:2244994945 OR from:api OR from:twittereng) -from:jack` | -| to: | Matches any Post replying to a specific user by X numeric Account ID or username (excluding `@`).
_Example_: `(to:2244994945 OR to:api OR to:twittereng) -to:jack` | -| url: | Performs a tokenized (keyword/phrase) match on expanded URLs of a post.
_Example_: `@XDevelopers url:"developer.x.com"` | -| url_title: | Performs a keyword/phrase match on the expanded URL HTML title metadata.
_Available only with PowerTrack and Historical PowerTrack._ | -| url_description: | Performs a keyword/phrase match on the expanded page description metadata.
_Available only with PowerTrack and Historical PowerTrack._ | -| url_contains: | Matches Posts with URLs containing the specified phrase or keyword.
Enclose search terms with punctuation in quotes.
_Example_: `(url_contains:"developer.x.com" OR url_contains:wildfire) -url_contains:reddit` | -| bio: | Matches a keyword or phrase within the user bio of a Post. This is a tokenized match within the 'description' field within the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object).
_Example_: `(bio:engineer OR bio:"wordpress.com" OR bio:🚀) -bio:troll`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| bio_name: | Matches a keyword within the user bio name of a Post. This is a tokenized match within a user’s “name” field in the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object).
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| bio_location: | Matches Posts where the User object's location contains the specified keyword or phrase.
This operator performs a tokenized match, similar to the normal keyword rules on the message body.
This location is part of the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object), and is the account's 'home' location.
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| statuses_count: | Matches Posts when the author has posted a number of statuses within the given range.
If a single number is specified, any number equal to or higher will match.
A range can be specified to match any number in the range (e.g., `statuses_count:1000..10000`).
_Example:_ `to:api statuses_count:10`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| followers_count: | Matches Posts when the author has a followers count within the given range.
If a single number is specified, any number equal to or higher will match.
A range can be specified to match any number in the range (e.g., `followers_count:1000..10000`).
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| friends_count: | Matches Posts when the author has a friends count (the number of users they follow) within the given range.
If a single number is specified, any number equal to or higher will match.
A range can be specified to match any number in the range (e.g., `friends_count:1000..10000`).
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| listed_count: | Matches Posts when the author has been listed within X a certain number of times within the given range.
If a single number is specified, any number equal to or higher will match.
A range can be specified to match any number in the range (e.g., `listed_count:10..100`).
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| $ | Matches any Post that contains the specified ‘cashtag’ entity.
_Example_: `($TWTR OR $TSLA OR $BRK.A) -$F`
_Note:_ The cashtag operator relies on X's ‘symbols’ entity extraction to match cashtags, rather than extracting it from the body itself. | -| retweets_of: | Matches Posts that are Retweets of a specified user.
Accepts both usernames and numeric X Account IDs (NOT Post status IDs).
_Example_: `(retweets_of:2244994945 OR retweets_of:api OR retweets_of:twittereng) -retweets_of:jack` | -| retweets_of_status_id: | Deliver only explicit Retweets of the specified Post. Use the ID of an original Post and not a Retweet.
_Example_: `retweets_of_status_id:1293593516040269825`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| in_reply_to_status_id: | Deliver only explicit replies to the specified Post.
_Example_: `in_reply_to_status_id:1293593516040269825`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| sample: | Returns a random sample of Posts that match a rule. The sample percentage must be an integer between 1 and 100.
The operator reduces the scope to X%, then the rule/filter is applied to that sampled subset.
_Example:_ `#happybirthday sample:5`
`"happy birthday"~5 sample:80`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| source: | Matches any Post generated by the specified source application. The value can be the application name or the application’s URL.
_Example:_ `#happybirthday source:"X for iPhone"`
`"This is a test X from my TestingApp" source:MyTestAppName`
_Note:_ The source operator searches on the Post source attribute and cannot be used alone. | -| lang: | Matches Posts classified by X as being in a particular language. Posts are currently classified as only one language, so matching multiple languages yields no results. _Not recommended to use alone._ | - -The list below represents the current supported languages and their corresponding BCP 47 language indentifier: - -| | | | | -| :--- | :--- | :--- | :--- | -| Amharic: am | German: de | Malayalam: ml | Slovak: sk | -| Arabic: ar | Greek: el | Maldivian: dv | Slovenian: sl | -| Armenian: hy | Gujarati: gu | Marathi: mr | Sorani Kurdish: ckb | -| Basque: eu | Haitian Creole: ht | Nepali: ne | Spanish: es | -| Bengali: bn | Hebrew: iw | Norwegian: no | Swedish: sv | -| Bosnian: bs | Hindi: hi | Oriya: or | Tagalog: tl | -| Bulgarian: bg | Latinized Hindi: hi-Latn | Panjabi: pa | Tamil: ta | -| Burmese: my | Hungarian: hu | Pashto: ps | Telugu: te | -| Croatian: hr | Icelandic: is | Persian: fa | Thai: th | -| Catalan: ca | Indonesian: in | Polish: pl | Tibetan: bo | -| Czech: cs | Italian: it | Portuguese: pt | Traditional Chinese: zh-TW | -| Danish: da | Japanese: ja | Romanian: ro | Turkish: tr | -| Dutch: nl | Kannada: kn | Russian: ru | Ukrainian: uk | -| English: en | Khmer: km | Serbian: sr | Urdu: ur | -| Estonian: et | Korean: ko | Simplified Chinese: zh-CN | Uyghur: ug | -| Finnish: fi | Lao: lo | Sindhi: sd | Vietnamese: vi | -| French: fr | Latvian: lv | Sinhala: si | Welsh: cy | -| Georgian: ka | Lithuanian: lt | | - -Example: - -(@XDevelopers OR to:XDevelopers) lang:es - -**Note:** The language operator matches on the specific Post language determined by X and set as the lang Post attribute.  See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) for more information on X Entities JSON attributes.  If no language classification can be made for a Post, the Post lang will be set as ‘und’ (for undefined). - -| Operator | Description | -|:--------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| place | Matches Posts tagged with the specified location or X place ID.
Multi-word place names should be enclosed in quotes.
_Example:_ `(place:London OR place:"Great Britain") -place:USA`
`place:fd70c22040963ac7`
**Note:** See the [GET geo/search](https://developer.x.com/en/docs/x-api/v1/geo/places-near-location/api-reference/get-geo-search) public API endpoint for how to obtain X place IDs.
**Note:** Will not match on Retweets or Quote Tweets, as Retweet places are attached to the original Post. | -| place_country | Matches Posts where the country code associated with a tagged place/location matches the given ISO alpha-2 character code.
_Example:_ `place_country:GB OR place_country:AU OR place_country:CA`
**Note:** Will not match on Retweets or Quote Tweets, as Retweet places are attached to the original Post.
Valid ISO codes: [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). | -| point_radius:[lon lat radius] | Matches against the Exact Location (x,y) of the Post or a “Place” geo polygon within the defined radius.
* Radius: < 25mi
* Supported units: mi, km
* Longitude: ±180
* Latitude: ±90
Coordinates are in decimal degrees.
Arguments are bracketed, space-delimited.
_Example:_ `point_radius:[-105.27346517 40.01924738 0.5mi]`
_Example:_ `point_radius:[2.355128 48.861118 16km]`
**Note:** Will not match on Retweets or Quote Tweets. | -| bounding_box:[west_long south_lat east_long north_lat] | Matches against Exact Location or a “Place” geo polygon fully contained in a bounding box.
Arguments are bracketed, space-delimited.
Coordinates: decimal degrees (±180 long, ±90 lat).
Width and height must be < 25mi.
_Example:_ `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]`
**Note:** Will not match on Retweets or Quote Tweets. | -| profile_country | Matches Posts where the author’s profile geo country code matches a given ISO-3166-1-alpha-2 two-letter code. | -| profile_region | Matches on the “region” field from the author’s profile geo enrichment, an exact full string match.
Use double quotes for substrings containing whitespace or punctuation.
_Example:_ `profile_region:"New York"` | -| profile_locality | Matches on the “locality” field from the author’s profile geo enrichment, an exact full string match.
Use double quotes for substrings containing whitespace or punctuation.
_Example:_ `profile_locality:"San Francisco"` | -| profile_subregion | Matches on the “subRegion” field from the author’s profile geo enrichment, including specific counties or metro areas.
An exact full string match.
_Example:_ `profile_subregion:"Santa Clara County"` | -| has:geo | Matches Posts with Post-specific geo location data from X, including “geo” lat-long or “Place” location data with a display name and geo polygon.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:profile_geo | Matches Posts with any Profile Geo metadata, regardless of value.
Available alias: `has:derived_user_geo`.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:links | Matches Posts with a link or referenced media in the "text" object of the payload, including media and Quote Tweets.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| is:retweet | Delivers only explicit retweets. Can be negated to exclude retweets and deliver only original content.
This operator looks only for true Retweets and not Quoted Tweets.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| is:reply | Delivers only explicit replies. Can be negated to exclude replies.
PowerTrack matches replies to original Posts, replies in quoted Posts, and replies in Retweets.
Search API matches only replies to original Posts.
_Example:_ `@XDevelopers -is:reply` | -| is:quote | Delivers only Quote Tweets or Posts that reference another Post.
Can be negated to exclude Quote Tweets.
_Example:_ `@XDevelopers is:quote` | -| is:verified | Delivers only Posts from “verified” authors. Can be negated to exclude Posts from verified authors.
_Example:_ `@XDevelopers is:verified` | -| has:mentions | Matches Posts mentioning another X user.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:hashtags | Matches Posts containing a hashtag.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:media | Matches Posts containing a media url classified by X (e.g., pic.x.com).
Available alias: `has:media_link`.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:images | Matches Posts containing a media url (e.g., pic.x.com).
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:videos | Matches Posts containing native X videos uploaded to X.
Available alias: `has:video_link`.
This operator does not match videos from YouTube, Periscope, or other video hosting sites.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:symbols | Matches Posts containing a cashtag symbol (e.g., $TWTR).
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | - - -## Operators by product -### Rules and filtering: Enterprise - -All enterprise operators are available with PowerTrack and Historical PowerTrack APIs. However, only a subset of operators are available to the enterprise Search APIs, as noted on this page. - -The dark blue tags note which operators are available to different enterprise products: - -PowerTrack Search - -| Operator | Product | Description | Matches on payload element | -| :--- | :--- | :--- | :--- | -| "exact phrase match" | PowerTrack

Search | Matches an exact phrase within the body of a Post.

Components that can translate into a search operators will be treated as words. In other words:

* `"#hashtag"` will match `hashtag` but not `#hashtag` (use the [hashtag operator](#hashtag-operator) without quotes to match on actual hashtags) 
* `"$TWTR"` will match the word `TWTR` but not the cashtag `$TWTR` (use the [cashtag operator](#cashtag-operator) without quotes to match on actual cashtags)

**Note:** in 30 Day Search and Full Archive Search (Enterprise and Premium), punctuation is not tokenized and is instead treated as whitespace. | `text` | -| @ | PowerTrack

Search | Matches any Post that mentions the given username. The value can be either the username (excluding the `@` character) or the user’s numeric ID or (obtained for example via the [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) endpoint). | `entities.user_mentions` | -| # | PowerTrack

Search | Matches any Post with the given hashtag.

This operator performs an exact match. For example meaning the rule `#1989` will match Posts containing the exact hashtag `#1989`, but not those with the hashtag `#TaylorSwift1989`.

**Note:** this operator relies on X's entity extraction to match hashtags, rather than extracting the hashtag from the body itself. For more details on JSON attributes from entities, refer to [X Entities](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary). | `entities.hashtags` | -| $ | PowerTrack

Search | Matches any Post that contains the specified cashtag (where the leading character of the token is `$`).

**Note: **this operator relies on X's entity extraction to match links, rather than extracting the link from the body itself. For more details on JSON attributes from entities, refer to [X Entities](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary). | `entities.symbols` | -| bio: | PowerTrack | _Available alias_: user_bio:

Matches a keyword (using tokenized match) or a phrase within the user bio of a Post. Use double quotes to match a phrase. In other words:

* `bio:software engineer` will match Posts with the keyword `engineer` from users with the word `software` in their bio
* `bio:"software engineer"` will match any Post posted by users with the phrase `software engineer` in their bio | `user``.description` | -| bio_location: | PowerTrack | _Available alias_: user\_bio\_location:

Matches Posts where the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object)'s location contains the specified keyword (using tokenized match) or phrase.

This location is a non-normalized, user-generated, free-form string, and is different from a Post's location (when available). | `user.location` | -| bio_name: | PowerTrack | Matches Posts where the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object)'s name contains the specified keyword (using tokenized match) or phrase. | `user.name` | -| bounding_box: | PowerTrack

Search | _Available alias_: geo\_bounding\_box:

Matches against the exact location (long, lat) of the Post (when present), and against a geo polygon (where the Place is fully contained within the defined region).

* west\_long south\_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude.
* east\_long and north\_lat represent the northeast corner of the bounding box, where east\_long is the longitude of that point, and north\_lat is the latitude.
* Width and height of the bounding box must be less than 25mi
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained within brackets, space delimited.

**Note:** operators matching on place (Post geo) will only include matches from original Posts. Retweets do not contain any place data. | `place` (original Posts only) | -| contains: | PowerTrack | Substring match for Posts that have the given substring in the body, regardless of tokenization. In other words, this does a pure substring match and does not consider word boundaries.

Use double quotes to match substrings that contain whitespace or punctuation. | `text` | -| <emoji> | PowerTrack

Search | Matches an emoji within the body of a Post.

This is a tokenized match, so your emoji will be matched against the tokenized text of the Post body. Tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Post with the text “I like 🍕” would be split into the following tokens: I, like, 🍕. These tokens would then be compared to the emoji used in your rule.

**Note:** if an emoji has a variant, you must use double quotes to add to a rule. | `text` | -| followers_count: | PowerTrack | Matches Posts when the author has a followers count within the given range.

* A single number (e.g. `followers_count:42`) will match any number equal to or greater than the value specified.
* A range (e.g. `followers_count:42..1337`) will match any number in the given range. | `user.followers_count` | -| friends_count: | PowerTrack | _Available alias_: following_count:

Matches Posts when the author has a friends count (the number of users they follow) that falls within the given range.

* A single number (e.g. `followers_count:42`) will match any number equal to or greater than the value specified.
* A range (e.g. `followers_count:42..1337`) will match any number in the given range. | `user.friends_count` | -| from: | PowerTrack

Search | Matches any Post from a specific user. The value can be either the username (excluding the `@` character) or the user’s numeric ID or (obtained for example via the [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) endpoint). | `user.id`, `user.id_str` (if using User ID)

`user.screen_name` (if using username) | -| has:geo | PowerTrack

Search | Matches Posts that have Post-specific geolocation data provided from X. This can be either “geo” lat-long coordinate, or a “location” in the form of a X [Place](https://dev.x.com/overview/api/places), with the corresponding display name, geo polygon, and other fields.

Cannot be used as a standalone operator.

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `place` (original Tweets only) | -| has:hashtags | PowerTrack

Search | Matches Posts that contain at least one hashtag.

Cannot be used as a standalone operator. | `entities.hashtags` | -| has:images | PowerTrack

Search | Matches Posts that contain at least one classified image URL.

Cannot be used as a standalone operator. | `entities.media` | -| has:lang | PowerTrack | Matches Posts that have been classified by X as being of a particular language.

If a Post has not been classified, the operator will not match. Each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results.

Cannot be used as a standalone operator. | `lang` when value is not `und` | -| has:links | PowerTrack

Search | This operator matches Posts which contain links in the Post body.

Cannot be used as a standalone operator.

**Note:** this operator relies on X's entity extraction to match links, rather than extracting the link from the body itself. For more details on JSON attributes from entities, refer to [X Entities](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary). | `entities.urls` | -| has:media | PowerTrack

Search | _Available alias_: has:media_link

Matches Posts that contain at least one classified media URL.

Cannot be used as a standalone operator. | `entities.media` | -| has:mentions | PowerTrack

Search | Matches Posts that mention another X user.

Cannot be used as a standalone operator. | `entities.user_mentions` | -| has:profile_geo | PowerTrack

Search | _Available alias_: has:derived\_user\_geo

Matches Posts that have any [Profile Geo](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) metadata, regardless of the actual value.

Cannot be used as a standalone operator. | `user.location` | -| has:symbols | PowerTrack

Enterprise | Matches Posts that contain a cashtag symbol (e.g. `$TWTR`).

Cannot be used as a standalone operator. | `entities.symbols` | -| has:videos | PowerTrack

Search | _Available alias_: has:video_link

Matches Posts that contain at least one classified media URL.

Cannot be used as a standalone operator. | `entities.media` | -| in\_reply\_to\_status\_id: | PowerTrack | _Available alias_: in\_reply\_to\_tweet\_id:

Deliver only explicit replies to the specified Post. | `id`, `id_str` of the target Post | -| is:quote | PowerTrack | Deliver explicit Quote Tweets that match a rule.

It can also be negated (`-is:quote`) to exclude Quote Tweets that match a rule from delivery.

Cannot be used as a standalone operator. | `is_quote_status` (if `true`) | -| is:reply | PowerTrack

Search | Deliver only replies that match a rule.

It can also be negated (`-is:reply`) to exclude delivery of replies that match the specified rule.

With PowerTrack, this operator matches on:

* Replies to an original Post
* Replies in quoted Posts
* Replies in Retweets


When used with the Search API, this operator matches on replies to an original Post, but excludes replies in quoted Tweets and replies in Retweets.

You can use this operators in conjunction with `is:retweet` and `is:quote` to only deliver replies to original Posts.

Cannot be used as a standalone operator with the Search API.

**Note**: with Premium, this operator is not available in Sandbox dev environments. | Reply elements, e.g. `in_reply_to_status_id` | -| is:retweet | PowerTrack

Search | Deliver only explicit Retweets that match a rule.

It can also be negated (`-is:retweet`) to exclude Retweets that match a rule from delivery and only original content is delivered.

This operator looks only for true Retweets (i.e. Retweets posted using the Retweet button). Quoted Tweets and modified Posts which do not use X's Retweet functionality will not be matched by this operator.

Cannot be used as a standalone operator. | Retweet elements, e.g. `retweeted_status` | -| is:verified | PowerTrack

Search | Deliver only Posts where the author is verified by X.

It can also be negated to exclude Posts where the author is verified.

Cannot be used as a standalone operator. | `user.verified` | -| keyword | PowerTrack

Search | Matches a keyword within the body of a Post.

This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body. Tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: `I`, `like`, `coca`, `cola`. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (e.g. coca-cola), symbol, or separator characters, you must use an [exact phrase match](#exact-match) operator. | `text` | -| lang: | PowerTrack

Search | Matches Posts that have been classified by X as being of a particular language (if, and only if, the post has been classified). Each Post will be classified with only one language, so AND’ing together multiple languages will yield no results.

**Note: **if no language classification can be made the provided result is `und` (for undefined).

This operator will only match against supported languages. Providing any other value (including `und`) will result in the operator being ignored (in other words, Posts will not be filtered by this operator). The list below represents the currently supported languages and their corresponding BCP 47 language identifier:

`am` Amharic

`hu` Hungarian

`pt` Portuguese

`ar` Arabic

`is` Icelandic

`ro` Romanian

`hy` Armenian

`in` Indonesian

`ru` Russian

`bn` Bengali

`it` Italian

`sr` Serbian

`bg` Bulgarian

`ja` Japanese

`sd` Sindhi

`my` Burmese

`kn` Kannada

`si` Sinhala

`zh` Chinese

`km` Khmer

`sk` Slovak

`cs` Czech

`ko` Korean

`sl` Slovenian

`da` Danish

`lo` Lao

`ckb` Sorani Kurdish

`nl` Dutch

`lv` Latvian

`es` Spanish

`en` English

`lt` Lithuanian

`sv` Swedish

`et` Estonian

`ml` Malayalam

`tl` Tagalog

`fi` Finnish

`dv` Maldivian

`ta` Tamil

`fr` French

`mr` Marathi

`te` Telugu

`ka` Georgian

`ne` Nepali

`th` Thai

`de` German

`no` Norwegian

`bo` Tibetan

`el` Greek

`or` Oriya

`tr` Turkish

`gu` Gujarati

`pa` Panjabi

`uk` Ukrainian

`ht` Haitian

`ps` Pashto

`ur` Urdu

`iw` Hebrew

`fa` Persian

`ug` Uyghur

`hi` Hindi

`pl` Polish

`vi` Vietnamese

`cy` Welsh | `lang` when value is not `und` | -| listed_count: | PowerTrack | _Available alias_: user\_in\_lists_count:

Matches Posts when the author has been listed on X a number of times falls within the given range.

* A single number (e.g. `listed_count:42`) will match any number equal to or greater than the value specified.
* A range (e.g. `listed_count:42..1337`) will match any number in the given range. | `user.listed_count` | -| place_country: | PowerTrack

Search | Matches Posts where the country code associated with a tagged [place/location](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-geo-objects) matches the given [ISO alpha-2 character code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

**Note:** operators matching on place (Post geo) will only include matches from original Posts. Retweets do not contain any place data. | `place` (original Posts only) | -| place: | PowerTrack

Search | Matches Posts tagged with specified location or [X place ID](https://developer.x.com/en/docs/x-api/v1/geo/places-near-location/api-reference/get-geo-search). Multi-word place names should be enclosed in quotes (e.g. `place:"San Francisco"`)

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `place` (original Posts only) | -| point_radius: | PowerTrack

Search | **Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `place` (original posts only) | -| profile\_bounding\_box:\[west\_long south\_lat east\_long north\_lat\] | PowerTrack | Matches against the user's exact Location (long, lat) in the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments) where the Place is fully contained within the defined region.

* west\_long south\_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude.
* east\_long and north\_lat represent the northeast corner of the bounding box, where east\_long is the longitude of that point, and north\_lat is the latitude.
* Width and height of the bounding box must be less than 25mi
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained within brackets, space delimited.

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `user.derived.locations.geo.coordinates` | -| profile_country: | PowerTrack

Search | Exact match on the country code from the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

Uses a normalized set of two-letter country codes, based on [ISO-3166-1-alpha-2 specification](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

To be concise, this operator is provided in lieu of an operator for the country field from the address object.

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `user.derived.locations.country_code` | -| profile_locality: | PowerTrack

Search | Exact match on the Locality field from the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

This is an exact full string match.

It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use `one/two`.

Use double quotes to match substrings that contain whitespace or punctuation, e.g. `profile_locality:"Lower East Side"`. | `user.derived.locations.locality` | -| profile\_point\_radius:\[lon lat radius\] | PowerTrack | Matches against the Exact Location (x,y) of the user's [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

* Units of radius supported are miles (mi) and kilometers (km).
* Radius must be less than 25mi.
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained within brackets, space delimited.

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `user.derived.locations.geo` | -| profile_region: | PowerTrack

Search | Exact match on the Region field from the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

This is an exact full string match.

It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use `one/two`.

Use double quotes to match substrings that contain whitespace or punctuation, e.g. `profile_locality:"New York"`. | `user.derived.locations.region` | -| profile_subregion: | PowerTrack | Exact match on the Subregion field from the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

This is an exact full string match.

It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use `one/two`.

Use double quotes to match substrings that contain whitespace or punctuation, e.g. `profile_locality:"Kings County"`. | `user.derived.locations.sub_region` | -| "keyword1 keyword2"~N | PowerTrack

Search | Commonly referred to as a proximity operator, this matches a Post where the keywords are no more than N tokens from each other.

If the keywords are in the opposite order, they can not be more than N-2 tokens from each other.

Can have any number of keywords in quotes.

N cannot be greater than 6. | `text` | -| retweets\_of\_status_id: | PowerTrack | _Available alias_: retweets\_of\_tweet_id:

Deliver only explicit Retweets of the specified original Post. | `retweeted_status.id`, `retweeted_status.id_str` | -| retweets_of: | PowerTrack

Search | _Available alias_: retweets\_of\_user:

Matches any Post that are Retweets of the given user. The value can be either the username (excluding the `@` character) or the user’s numeric ID or (obtained for example via the [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) endpoint). | `retweeted_status.id` (if present) | -| sample: | PowerTrack | Returns a random percent sample of Posts that match a rule rather than the entire set of Posts. The percent value must be represented by an integer between 1 and 100.

This operator applies to the entire rule and requires all OR'd terms to be grouped.

**Note:** the sample operator first reduces the scope of the firehose to X%, then the rule/filter is applied to that sampled subset. If you are using, for example, `sample:10`, each Post has a 10% chance of being in the sample. 

**Note:** the sampling is deterministic, and you will get the same data sample in realtime as you would if you pulled the data historically. | | -| source: | PowerTrack | Matches any Post generated by the given source application. The value must be either the name of the application or the application’s URL.

Cannot be used as a standalone operator. | `source` | -| statuses_count: | PowerTrack | _Available alias_: tweets_count:

Matches Posts when the author has posted a number of statuses that falls within the given range.

* A single number (e.g. `statuses_count:42`) will match any number equal to or greater than the value specified.
* A range (e.g. `statuses_count:42..1337`) will match any number in the given range. | `user``.statuses_count` | -| to: | PowerTrack

Search | Matches any Post that is in reply to a particular user. The value can be either the username (excluding the `@` character) or the user’s numeric ID or (obtained for example via the [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) endpoint). | `text` | -| url: | PowerTrack

Search | Performs a tokenized match on the expanded URLs of a Post. Tokens and phrases containing punctuation or special characters should be double-quoted (e.g. `url:"/developer"`).

While generally not recommended, the operator can also match on a specific protocol, enclosed in double-quotes (e.g. `url:"https://developer.x.com"`). | `entities.urls.expanded_url` | -| url_contains: | PowerTrack | Performs a keyword/phrase match on the (new) [expanded URL title metadata enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments). | `entities.urls.expanded_url` | -| url_description: | PowerTrack | _Available alias_: within\_url\_description:

Performs a keyword/phrase match on the (new) [expanded page description metadata enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments). | `entities.urls.unwound.description` | -| url_title: | PowerTrack | _Available alias_: within\_url\_title:

Performs a keyword/phrase match on the (new) [expanded URL title metadata enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments). | `entities.urls.title` | diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/search-api.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/search-api.mdx deleted file mode 100644 index 01c46bcd6..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/search-api.mdx +++ /dev/null @@ -1,1465 +0,0 @@ ---- -title: "Search API: Enterprise" -sidebarTitle: Search API -keywords: ["enterprise search", "GNIP search", "enterprise search API", "search API enterprise", "enterprise search endpoints"] ---- - ->**Please note:** -> ->We have released a new version of [search Posts](/x-api/posts/search/introduction) and [Post counts](/x-api/posts/counts/introduction) in [X API v2](/x-api/getting-started/about-x-api). We encourage you to [review what's new](/x-api/migrate/overview) with X API v2.  -> ->These endpoints have been updated to include Post edit metadata. Learn more about these metadata on the ["Edit Posts" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets).  - -## Overview - -`Enterprise` - -_The enterprise APIs are available within our managed access levels only. To use these APIs, you must first set up an account with our enterprise sales team. To learn more see [HERE](https://developer.x.com/en/products/x-api/enterprise)._ - -_You can view all of the X API search Post offerings [HERE](/x-api/enterprise-gnip-2.0/fundamentals/search-api)._ - -There are two enterprise search APIs: - -1. 30-Day Search API provides data from the previous 30 days. -2. Full-Archive Search API provides complete and instant access to the full corpus of X data dating all the way back to the first Post in March 2006. - -These RESTful APIs supports a single query of up to 2,048 characters per request. Queries are written with the PowerTrack rule syntax - see [Rules and filtering](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#getting-started-with-enterprise-rules-and-queries) for more details. Users can specify any time period, to the granularity of a minute. However, responses will be limited to the lesser of your specified maxResults OR 31 days and include a next token to paginate for the next set of results. If time parameters are not specified, the API will return matching data from the 30 most recent days. - -The enterprise search APIs provide low-latency, full-fidelity, query-based access to the Post archive with minute granularity. Post data is served in reverse chronological order, starting with the most recent Post that matches your query. Posts are available from the search API approximately 30 seconds after being published. - -These search endpoints provide edited Post metadata. All objects for Posts created since September 29, 2022, include Post edit metadata, even if the Post was never edited. Each time a Post is edited, a new Post ID is created. A Post's edit history is documented by an array of Post IDs, starting with the original ID. - -These endpoints will always return the most recent edit, along with any edit history. Any Post collected after its 30-minute edit window will represent its final version. To learn more about Edit Post metadata, check out the [Edit Posts fundamentals](/x-api/fundamentals/edit-posts) page. - -Requests include a maxResultsparameter that specifies the maximum number of Posts to return per API response. If more Posts are associated with the query than this maximum amount of results per response, a next token is included in the response. These next tokens are used in subsequent requests to page through the entire set of Posts associated with the query. - -These enterprise search APIs provide a _counts_ endpoint that enables users to request the data volume associated with their query.  - -### Request types - -The enterprise search APIs support two types of requests: - -#### Search requests (data) - -Search requests to the enterprise search APIs allow you to retrieve up to 500 results per response for a given timeframe, with the ability to paginate for additional data. Using the maxResults parameter, you can specify smaller page sizes for display use cases (allowing your user to request more results as needed) or larger page sizes (up to 500) for larger data pulls. The data is delivered in reverse chronological order and compliant at the time of delivery. - -#### Counts requests (Post count) - -Counts requests provide the ability to retrieve historical activity counts, which reflect the number of activities that occurred which match a given query during the requested timeframe. The response will essentially provide you with a histogram of counts, bucketed by day, hour, or minute (the default bucket is _hour_). It's important to note that counts results do not always reflect compliance events (e.g., Posts deletes) that happen well after (7+ days) a Post is published; therefore, it is expected that the counts metric may not always match that of a data request for the same query. - -**Billing note:** each request – _including pagination requests_ – made against the data and counts endpoints are counted as a billed request. Therefore, if there are multiple pages of results for a single query, paging through the X pages of results would equate to X requests for billing. - -### Available operators - -Enterprise search APIs support rules with up to 2,048 characters. The enterprise search APIs support the operators listed below. For detailed descriptions see [HERE](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-operators).  - -| | | | | -| :--- | :--- | :--- | :--- | -| **Matching on Post contents:** | **Matching on accounts of interest:** | **Post attributes:** | **Geospatial operators:** | -| * keyword
* “quoted phrase”
* “keyword1 keyword2”~N
* #
* @
* $
* url:
* lang: | * from:
* to:
* retweets_of: | * is:retweet

* has:mentions
* has:hashtags
* has:media
* has:videos
* has:images
* has:links
* has:symbols
* is:verified

* -is:nullcast (negation only operator) | * bounding\_box:\[west\_long south\_lat east\_long north_lat\]
* point_radius:\[lon lat radius\]
* has:geo
* place:
* place_country:
* has:profile_geo
* profile_country:
* profile_region:
* profile_locality: | - - -Notes: Do not embed/nest operators ("#cats") will resolve to cats with the search APIs.   The ‘lang:’ operator and all ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @XDevelopers has:links).     - -Search APIs use a limited set of operators due to tokenization/matching functionality. enterprise real-time and batched historical APIs provide additional operators. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#operators-by-product) for more details. - -For more details, please see the [Getting started with operators](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#building-rules-and-queries) guide. - -### Data availability / important date - -When using the Full-Archive search API, keep in mind that the X platform has continued to evolve since 2006. As new features were added, the underlying JSON objects have had new metadata added to it. For that reason it is important to understand when Post attributes were added that search operators match on. Below are some of the more fundamental 'born on' dates of important groups of metadata. To learn more about when Post attributes were first introduced, see [this guide](/x-api/enterprise-gnip-2.0/fundamentals/search-api#full-archive-search-metadata-timeline).   - -* First Post: 3/21/2006 -* First Native Retweets: 11/6/2009 -* First Geo-tagged Post: 11/19/2009 -* URLs first indexed for filtering: 8/27/2011 -* Enhanced URL expansion metadata (website titles and descriptions): 12/1/2014 -* Profile Geo enrichment metadata and filtering: 2/17/2015 - -### Data Updates and Mutability - -With the enterprise search APIs, some of the data within a Post is mutable, i.e. can be updated or changed after initial archival. - -This mutable data falls into two categories: - -* User object metadata: - * User’s @handle (numeric ID does not ever change) - * Bio description - * Counts: statuses, followers, friends, favorites, lists - * Profile location - * Other details such as time zone and language -* Post statistics - i.e. anything that can be changed on the platform by user actions (examples below): - * Favorites count - * Retweet count - -In most of these cases, the search APIs will return data as it exists on the platform at _query-time_, rather than Post generation time. However, in the case of queries using select operators (e.g. from, to, @, is:verified), this may not be the case. Data is updated in our index on a regular basis, with an increased frequency for most recent timeframes. As a result, in some cases, the data returned may not exactly match the current data as displayed on X.com, but matches data at the time it was last indexed. - -Note, this issue of inconsistency only applies to queries where the operator applies to mutable data. One example is filtering for usernames, and the best workaround would be to use user numeric IDs rather than @handles for these queries. - -### Single vs. Multi-threaded Requests - -Each customer has a defined rate limit for their search endpoint. The default per-minute rate limit for Full-Archive search is 120 requests per minute, for an average of 2 queries per second (QPS). This average QPS means that, in theory, 2 requests can be made of the API every second. Given the pagination feature of the product, if a one-year query has one million Posts associated with it, spread evenly over the year, over 2,000 requests would be required (assuming a ‘maxResults’ of 500) to receive all the data. Assuming it takes two seconds per response, that is 4,000 seconds (or just over an hour) to pull all of that data serially/sequentially through a single thread (1 request per second using the prior response’s “next” token). Not bad! - -Now consider the situation where twelve parallel threads are used to receive data. Assuming an even distribution of the one million Posts over the one-year period, you could split the requests into twelve parallel threads (multi-threaded) and utilize more of the per-second rate limit for the single “job”. In other words, you could run one thread per-month you are interested in and by doing so, data could be retrieved 12x as fast (or ~6 minutes). - -This multi-threaded example applies equally well to the counts endpoint. For example, if you wanted to receive Post counts for a two-year period, you could make a single-threaded request and page back through the counts 31 days at a time. Assuming it takes 2 seconds per response, it would take approximately 48 seconds to make the 24 API requests and retrieve the entire set of counts. However, you also have the option to make multiple one-month requests at a time. When making 12 requests per second, the entire set of counts could be retrieved in approximately 2 seconds. - -### Retry Logic - -If you experience a 503 error with the enterprise search APIs, it is likely a transient error and can be resolved by re-trying the request a short time later. - -If the request fails 4 times in a row, and you have waited at least 10 minutes between failures, use the following steps to troubleshoot: - -* Retry the request after reducing the amount of time it covers. Repeat this down to a 6-hour time window if unsuccessful. -* If you are ORing a large number of terms together, split them into separate rules and retry each individually. -* If you are using a large number of exclusions in your rule, reduce the number of negated terms in the rule and retry. - -## Quick start - -### Getting started with enterprise Search Posts: 30-Day API - -The enterprise Search Posts: 30-Day API provides you with Posts posted within the last 30 days. Posts are matched and sent back to you based on the query you specify in your request. A query is a rule in which you define what the Post you get back should contain. In this tutorial, we will search for Posts originating from the X account @XDevelopers in English. - -The Posts you get back in your payload can be in a data format, which provides you with the full Post payload, or it can be in a counts format which gives you numerical count data of matched Posts. We will be using cURL to make requests to the data and counts endpoints. - -You will need the following: - -* [An enterprise account]https://developer.x.com/en/products/x-api/enterprise -* Your username, password, and account name -* Label associated with your search endpoint, as displayed at console.gnip.com - -#### Accessing the data endpoint - - -The data endpoint will provide us with the full Post payload of matched Posts. We will use the `from:` and `lang:` operators to find Posts originating from @XDevelopers in English. _For more operators [click here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-operators)._ - - -_cURL is a command-line tool for getting or sending files using the URL syntax._ - -Copy the following cURL request into your command line after making changes to the following: - -* **Username** `` e.g. `email@domain.com` - -* **Account name** `` e.g. `john-doe` - -* **Label** ` - - -```bash -_This is an example cURL request. If you try to run this it will not work._ - -curl -X POST -uemail@domain.com "https://gnip-api.x.com/search/30day/accounts/john-doe/prod.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"201811100000","toDate":"201812012359"}' -``` - - - -#### Data endpoint response payload - -The payload you get back from your API request will appear in JSON format, as shown below. -```json -{ - "results": [ - { - "created_at": "Fri Nov 02 17:18:31 +0000 2018", - "id": 1058408022936977409, - "id_str": "1058408022936977409", - "text": "RT @harmophone: \"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conv…", - "source": "Twitter Web Client<\/a>", - "truncated": false, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "Twitter Dev", - "screen_name": "TwitterDev", - "location": "Internet", - "url": "https:\/\/developer.x.com\/", - "description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https:\/\/devcommunity.com\/ ⌨️ #TapIntoTwitter", - "translator_type": "null", - "protected": false, - "verified": true, - "followers_count": 503828, - "friends_count": 1477, - "listed_count": 1437, - "favourites_count": 2199, - "statuses_count": 3380, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": "en", - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "null", - "profile_background_image_url": "null", - "profile_background_image_url_https": "null", - "profile_background_tile": null, - "profile_link_color": "null", - "profile_sidebar_border_color": "null", - "profile_sidebar_fill_color": "null", - "profile_text_color": "null", - "profile_use_background_image": null, - "profile_image_url": "null", - "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg", - "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "retweeted_status": { - "created_at": "Tue Oct 30 21:30:25 +0000 2018", - "id": 1057384253116289025, - "id_str": "1057384253116289025", - "text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relev… https:\/\/t.co\/w46U5TRTzQ", - "source": "Twitter Web Client<\/a>", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 175187944, - "id_str": "175187944", - "name": "Tyler Singletary", - "screen_name": "harmophone", - "location": "San Francisco, CA", - "url": "http:\/\/medium.com\/@harmophone", - "description": "SVP Product at @Tagboard. Did some Data, biz, and product @Klout & for @LithiumTech; @BBI board member; @Insightpool advisor. World's worst whiteboarder.", - "translator_type": "null", - "protected": false, - "verified": false, - "followers_count": 1982, - "friends_count": 1877, - "listed_count": 245, - "favourites_count": 23743, - "statuses_count": 12708, - "created_at": "Thu Aug 05 22:59:29 +0000 2010", - "utc_offset": null, - "time_zone": null, - "geo_enabled": false, - "lang": "en", - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "null", - "profile_background_image_url": "null", - "profile_background_image_url_https": "null", - "profile_background_tile": null, - "profile_link_color": "null", - "profile_sidebar_border_color": "null", - "profile_sidebar_fill_color": "null", - "profile_text_color": "null", - "profile_use_background_image": null, - "profile_image_url": "null", - "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg", - "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conversations in real-time and enabling voters to ask questions during debates,”  -- @adamostrow, @TEGNA\nLearn More: https:\/\/t.co\/ivAFtanfje", - "display_text_range": [ - 0, - 259 - ], - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https:\/\/t.co\/ivAFtanfje", - "expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4", - "display_url": "blog.tagboard.com\/twitter-and-ta…", - "unwound": { - "url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4", - "status": 200, - "title": "Twitter and Tagboard Collaborate to Bring Best Election Content to News Outlets With Tagboard…", - "description": "By Tyler Singletary, Head of Product, Tagboard" - }, - "indices": [ - 236, - 259 - ] - } - ], - "user_mentions": [ - { - "screen_name": "adamostrow", - "name": "Adam Ostrow", - "id": 5695942, - "id_str": "5695942", - "indices": [ - 204, - 215 - ] - }, - { - "screen_name": "TEGNA", - "name": "TEGNA", - "id": 34123003, - "id_str": "34123003", - "indices": [ - 217, - 223 - ] - } - ], - "symbols": [] - } - }, - "quote_count": 0, - "reply_count": 1, - "retweet_count": 6, - "favorite_count": 19, - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https:\/\/t.co\/w46U5TRTzQ", - "expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025", - "display_url": "twitter.com\/i\/web\/status\/1…", - "indices": [ - 117, - 140 - ] - } - ], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en" - }, - "is_quote_status": false, - "quote_count": 0, - "reply_count": 0, - "retweet_count": 0, - "favorite_count": 0, - "entities": { - "hashtags": [], - "urls": [], - "user_mentions": [ - { - "screen_name": "harmophone", - "name": "Tyler Singletary", - "id": 175187944, - "id_str": "175187944", - "indices": [ - 3, - 14 - ] - } - ], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [ - { - "tag": null - } - ] - } - ], - "requestParameters": { - "maxResults": 100, - "fromDate": "201811010000", - "toDate": "201811060000" - } -} -``` - -#### Accessing the counts endpoint - -With the counts endpoint, we’ll retrieve the number of Posts originating from the @XDevelopers account in English grouped by `day`. - - - -_cURL is a command-line tool for getting or sending files using the URL syntax._ - -Copy the following cURL request into your command line after making changes to the following: - -* **Username** `` e.g. `email@domain.com` - -* **Account name** `` e.g. `john-doe` - -* **Label** ` - - -_This is an example cURL request. If you try to run this it will not work._ - -```bash -curl -X POST -uemail@domain.com "https://gnip-api.x.com/search/30day/accounts/john-doe/prod/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"201811100000","toDate":"201812012359","bucket":"day"}' -``` - - - -#### Counts endpoint response payload - -The payload you get back from your API request will appear in JSON format, as shown below. -```json -{ - "results": [ - { - "timePeriod": "201811010000", - "count": 0 - }, - { - "timePeriod": "201811020000", - "count": 1 - }, - { - "timePeriod": "201811030000", - "count": 0 - }, - { - "timePeriod": "201811040000", - "count": 0 - }, - { - "timePeriod": "201811050000", - "count": 0 - } - ], - "totalCount": 1, - "requestParameters": { - "bucket": "day", - "fromDate": "201811010000", - "toDate": "201811060000" - } -} -``` -Great job! Now you've successfully accessed the enterprise Search Posts: 30-Day API. - -##### **Referenced articles** - -* [Introduction to Post objects](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) -* [Search operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-operators) -* [Post objects and payloads](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#post-object) - -### Getting started with enterprise Search Posts: Full-Archive API - -The enterprise Search Posts: Full-Archive API provides you with Posts since the first one posted in 2006. Posts are matched and sent back to you based on the query you specify in your request. A query is a rule in which you define what the Post you get back should contain. In this tutorial, we will search for Posts originating from the X account @XDevelopers in English. - -The Posts you get back in your payload can be in a data format, which provides you with the full Post payload, or it can be in a counts format which gives you numerical count data of matched Posts. We will be using cURL to make requests to the data and counts endpoints. - -You will need the following: - -* [An enterprise account]https://developer.x.com/en/products/x-api/enterprise -* Your username, password, and account name -* Label associated with your search endpoint, as displayed at console.gnip.com - -#### Accessing the data endpoint - - -The data endpoint will provide us with the full Post payload of matched Posts. We will use the `from:` and `lang:` operators to find Posts originating from @XDevelopers in English. _For more operators [click here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-operators)._ - -* [cURL](#tab1) -* [cURL example](#tab2) - - - -_cURL is a command-line tool for getting or sending files using the URL syntax._ - -Copy the following cURL request into your command line after making changes to the following: - -* **Username** `` e.g. `email@domain.com` - -* **Account name** `` e.g. `john-doe` - -* **Label** ` - -_This is an example cURL request. If you try to run this it will not work._ - -```bash -curl -X POST -uemail@domain.com "https://gnip-api.x.com/search/fullarchive/accounts/john-doe/prod.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"201802010000","toDate":"201802282359"}' -``` - - - - -##### Data endpoint response payload - -The payload you get back from your API request will appear in JSON format, as shown below. - -```json -{ - "results": [ - { - "created_at": "Fri Nov 02 17:18:31 +0000 2018", - "id": 1058408022936977409, - "id_str": "1058408022936977409", - "text": "RT @harmophone: \"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conv…", - "source": "Twitter Web Client<\/a>", - "truncated": false, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "Twitter Dev", - "screen_name": "TwitterDev", - "location": "Internet", - "url": "https:\/\/developer.x.com\/", - "description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https:\/\/devcommunity.com\/ ⌨️ #TapIntoTwitter", - "translator_type": "null", - "protected": false, - "verified": true, - "followers_count": 503828, - "friends_count": 1477, - "listed_count": 1437, - "favourites_count": 2199, - "statuses_count": 3380, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": "en", - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "null", - "profile_background_image_url": "null", - "profile_background_image_url_https": "null", - "profile_background_tile": null, - "profile_link_color": "null", - "profile_sidebar_border_color": "null", - "profile_sidebar_fill_color": "null", - "profile_text_color": "null", - "profile_use_background_image": null, - "profile_image_url": "null", - "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg", - "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "retweeted_status": { - "created_at": "Tue Oct 30 21:30:25 +0000 2018", - "id": 1057384253116289025, - "id_str": "1057384253116289025", - "text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relev… https:\/\/t.co\/w46U5TRTzQ", - "source": "Twitter Web Client<\/a>", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 175187944, - "id_str": "175187944", - "name": "Tyler Singletary", - "screen_name": "harmophone", - "location": "San Francisco, CA", - "url": "http:\/\/medium.com\/@harmophone", - "description": "SVP Product at @Tagboard. Did some Data, biz, and product @Klout & for @LithiumTech; @BBI board member; @Insightpool advisor. World's worst whiteboarder.", - "translator_type": "null", - "protected": false, - "verified": false, - "followers_count": 1982, - "friends_count": 1877, - "listed_count": 245, - "favourites_count": 23743, - "statuses_count": 12708, - "created_at": "Thu Aug 05 22:59:29 +0000 2010", - "utc_offset": null, - "time_zone": null, - "geo_enabled": false, - "lang": "en", - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "null", - "profile_background_image_url": "null", - "profile_background_image_url_https": "null", - "profile_background_tile": null, - "profile_link_color": "null", - "profile_sidebar_border_color": "null", - "profile_sidebar_fill_color": "null", - "profile_text_color": "null", - "profile_use_background_image": null, - "profile_image_url": "null", - "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg", - "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conversations in real-time and enabling voters to ask questions during debates,”  -- @adamostrow, @TEGNA\nLearn More: https:\/\/t.co\/ivAFtanfje", - "display_text_range": [ - 0, - 259 - ], - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https:\/\/t.co\/ivAFtanfje", - "expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4", - "display_url": "blog.tagboard.com\/twitter-and-ta…", - "unwound": { - "url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4", - "status": 200, - "title": "Twitter and Tagboard Collaborate to Bring Best Election Content to News Outlets With Tagboard…", - "description": "By Tyler Singletary, Head of Product, Tagboard" - }, - "indices": [ - 236, - 259 - ] - } - ], - "user_mentions": [ - { - "screen_name": "adamostrow", - "name": "Adam Ostrow", - "id": 5695942, - "id_str": "5695942", - "indices": [ - 204, - 215 - ] - }, - { - "screen_name": "TEGNA", - "name": "TEGNA", - "id": 34123003, - "id_str": "34123003", - "indices": [ - 217, - 223 - ] - } - ], - "symbols": [] - } - }, - "quote_count": 0, - "reply_count": 1, - "retweet_count": 6, - "favorite_count": 19, - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https:\/\/t.co\/w46U5TRTzQ", - "expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025", - "display_url": "twitter.com\/i\/web\/status\/1…", - "indices": [ - 117, - 140 - ] - } - ], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en" - }, - "is_quote_status": false, - "quote_count": 0, - "reply_count": 0, - "retweet_count": 0, - "favorite_count": 0, - "entities": { - "hashtags": [], - "urls": [], - "user_mentions": [ - { - "screen_name": "harmophone", - "name": "Tyler Singletary", - "id": 175187944, - "id_str": "175187944", - "indices": [ - 3, - 14 - ] - } - ], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [ - { - "tag": null - } - ] - } - ], - "requestParameters": { - "maxResults": 100, - "fromDate": "201811010000", - "toDate": "201811060000" - } -} -``` - - -#### Accessing the counts endpoint - -With the counts endpoint, we’ll retrieve the number of Posts originating from the @XDevelopers account in English grouped by `day`. - - - -_cURL is a command-line tool for getting or sending files using the URL syntax._ - -Copy the following cURL request into your command line after making changes to the following: - -* **Username** `` e.g. `email@domain.com` - -* **Account name** `` e.g. `john-doe` - -* **Label** ` - -```bash -_This is an example cURL request. If you try to run this it will not work._ - -curl -X POST -uemail@domain.com "https://gnip-api.x.com/search/fullarchive/accounts/john-doe/prod/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"201802010000","toDate":"201802282359","bucket":"day"}' -``` - - - -#### Counts endpoint response payload - -The payload you get back from your API request will appear in JSON format, as shown below. -```json -{ - "results": [ - { - "timePeriod": "201811010000", - "count": 0 - }, - { - "timePeriod": "201811020000", - "count": 1 - }, - { - "timePeriod": "201811030000", - "count": 0 - }, - { - "timePeriod": "201811040000", - "count": 0 - }, - { - "timePeriod": "201811050000", - "count": 0 - } - ], - "totalCount": 1, - "requestParameters": { - "bucket": "day", - "fromDate": "201811010000", - "toDate": "201811060000" - } -} -``` -Great job! Now you've successfully accessed the enterprise Search Posts: Full-Archive API. - -##### Referenced articles - -* [Introduction to Post objects](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) -* [Search operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-operators) -* [Post objects and payloads](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#post-object) - -## Guides -### Building search queries - -### Enterprise operators - -Below is a list of all operators supported in X's enterprise search APIs: - -* **Enterprise** 30-day search API -* **Enterprise** Full-archive search API - -For a side-by-side comparison of available operators by product see [HERE](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#operators-by-product). - -|Operator|Description| -|:--------|:------------------| -| keyword | Matches a tokenized keyword within the body or urls of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (for example, coca-cola), symbol, or separator characters, you must use a quoted exact match as described below.

**Note:** With the Search API, accented and special characters are normalized to standard latin characters, which can change meanings in foreign languages or return unexpected results:
For example, "músic" will match “music” and vice versa.
For example, common phrases like "Feliz Año Nuevo!" in Spanish, would be indexed as "Feliz Ano Nuevo", which changes the meaning of the phrase.

**Note:** This operator will match on both URLs and unwound URLs within a Post. | -|emoji|Matches an emoji within the body of a Post. Emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Post with the text “I like ” would be split into the following tokens: I, like, . These tokens would then be compared to the emoji used in your rule. Note that if an emoji has a variant, you must use “quotations” to add to a rule. | -|"exact phrase match" |Matches the tokenized and ordered phrase within the body or urls of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters.

**Note:** Punctuation is not tokenized and is instead treated as whitespace.
For example, quoted “#hashtag” will match “hashtag” but not #hashtag (use the hashtag # operator without quotes to match on actual hashtags.
For example, quoted “$cashtag” will match “cashtag” but not $cashtag (use the cashtag $ operator without quotes to match on actual cashtags.
For example, "Love Snow" will match "#love #snow"
For example, "#Love #Snow" will match "love snow"

**Note:** This operator will match on both URLs and unwound URLs within a Post.| -|"keyword1 keyword2"~N|Commonly referred to as a proximity operator, this matches a Post where the keywords are no more than N tokens from each other.

If the keywords are in the opposite order, they can not be more than N-2 tokens from each other. Can have any number of keywords in quotes. N cannot be greater than 6.

Note that this operator is only available in the `enterprise` search APIs.| -|from:| Matches any Post from a specific user.
The value must be the user’s X numeric Account ID or username (excluding the @ character). See [HERE](/x-api/users/lookup/introduction) or [HERE](http://gettwitterid.com/) for methods for looking up numeric X Account IDs.| -|to:|Matches any Post that is in reply to a particular user.

The value must be the user’s numeric Account ID or username (excluding the @ character). See [HERE](/x-api/users/lookup/introduction) for methods for looking up numeric X Account IDs.| -|url:|Performs a tokenized (keyword/phrase) match on the expanded URLs of a Post (similar to url_contains). Tokens and phrases containing punctuation or special characters should be double-quoted. For example, url:"/developer". While generally not recommended, if you want to match on a specific protocol, enclose in double-quotes: url:"https://developer.x.com".
**Note:** When using PowerTrack or Historical PowerTrack, this operator will match on URLs contained within the original Post of a Quote Post. For example, if your rule includes url:"developer.x.com", and a Post contains that URL, any Quote Tweets of that Post will be included in the results. This is not the case when using the Search API.| -|#|Matches any Post with the given hashtag.

This operator performs an exact match, NOT a tokenized match, meaning the rule “2016” will match posts with the exact hashtag “2016”, but not those with the hashtag “2016election”

Note: that the hashtag operator relies on X's entity extraction to match hashtags, rather than extracting the hashtag from the body itself. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#hashtags) for more information on X Entities JSON attributes.| -|@|Matches any Post that mentions the given username.
The to: operator returns a subset match of the @mention operator.| -|$|Matches any Post that contains the specified ‘cashtag’ (where the leading character of the token is the ‘$’ character).

Note that the cashtag operator relies on X's ‘symbols’ entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#symbols) for more information on X Entities JSON attributes.

Note that this operator is only available in the `enterprise` search APIs.

| -|retweets_of:|_Available alias_: retweets\_of\_user:
Matches Posts that are retweets of a specified user. Accepts both usernames and numeric X Account IDs (NOT Post status IDs).See [HERE](/x-api/users/lookup/introduction) for methods for looking up numeric X Account IDs.| -|lang:|Matches Posts that have been classified by X as being of a particular language (if, and only if, the post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results.

**Note:** if no language classification can be made the provided result is ‘und’ (for undefined).

The list below represents the current supported languages and their corresponding BCP 47 language indentifier:
- -| | | | | -| :--- | :--- | :--- | :--- | -| Amharic: am | German: de | Malayalam: ml | Slovak: sk | -| Arabic: ar | Greek: el | Maldivian: dv | Slovenian: sl | -| Armenian: hy | Gujarati: gu | Marathi: mr | Sorani Kurdish: ckb | -| Basque: eu | Haitian Creole: ht | Nepali: ne | Spanish: es | -| Bengali: bn | Hebrew: iw | Norwegian: no | Swedish: sv | -| Bosnian: bs | Hindi: hi | Oriya: or | Tagalog: tl | -| Bulgarian: bg | Latinized Hindi: hi-Latn | Panjabi: pa | Tamil: ta | -| Burmese: my | Hungarian: hu | Pashto: ps | Telugu: te | -| Croatian: hr | Icelandic: is | Persian: fa | Thai: th | -| Catalan: ca | Indonesian: in | Polish: pl | Tibetan: bo | -| Czech: cs | Italian: it | Portuguese: pt | Traditional Chinese: zh-TW | -| Danish: da | Japanese: ja | Romanian: ro | Turkish: tr | -| Dutch: nl | Kannada: kn | Russian: ru | Ukrainian: uk | -| English: en | Khmer: km | Serbian: sr | Urdu: ur | -| Estonian: et | Korean: ko | Simplified Chinese: zh-CN | Uyghur: ug | -| Finnish: fi | Lao: lo | Sindhi: sd | Vietnamese: vi | -| French: fr | Latvian: lv | Sinhala: si | Welsh: cy | -| Georgian: ka | Lithuanian: lt | | - -||| -|:----|:---| -|place:|Matches Posts tagged with the specified location _or_ X place ID (see examples). Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes.

**Note:** See the [GET geo/search](https://developer.x.com/en/docs/x-api/v1/geo/place-information/overview) public API endpoint for how to obtain X place IDs.

**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.| -|place_country:|Matches Posts where the country code associated with a tagged [place](https://developer.x.com/en/docs/x-api/v1/geo/place-information/overview) matches the given ISO alpha-2 character code.

Valid ISO codes can be found here: [http://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.| -|point_radius:\[lon lat radius\]|Matches against the Exact Location (x,y) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region.

* Units of radius supported are miles (mi) and kilometers (km).
* Radius must be less than 25mi.
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained with brackets, space delimited.

**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.| -|bounding\_box:\[west\_long south\_lat east\_long north_lat\]|_Available alias_: geo\_bounding\_box:

Matches against the Exact Location (long, lat) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region.

* west\_long south\_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude.
* east\_long and north\_lat represent the northeast corner of the bounding box, where east\_long is the longitude of that point, and north\_lat is the latitude.
* Width and height of the bounding box must be less than 25mi
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained with brackets, space delimited.
**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. -|profile_country:|Exact match on the “countryCode” field from the “address” object in the Profile Geo enrichment.
Uses a normalized set of two-letter country codes, based on ISO-3166-1-alpha-2 specification. This operator is provided in lieu of an operator for “country” field from the “address” object to be concise.| -|profile_region:|Matches on the “region” field from the “address” object in the Profile Geo enrichment.

This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation.| -|profile_locality:|Matches on the “locality” field from the “address” object in the Profile Geo enrichment.

This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation.| - - - **NOTE:** All is: and has: operators cannot be used as standalone operators when using the Search API, and must be combined with another clause. - -For example, @XDeevelopers has:links - - -| | | -| :--- | :--- | -| has:geo | Matches Posts that have Post-specific geo location data provided from X. This can be either “geo” lat-long coordinate, or a “location” in the form of a X [“Place”](https://dev.x.com/overview/api/places), with corresponding display name, geo polygon, and other fields.



**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:profile_geo | _Available alias_: has:derived\_user\_geo

Matches Posts that have any [Profile Geo](http://support.gnip.com/enrichments/profile_geo.html) metadata, regardless of the actual value.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:links | This operators matches Posts which contain links in the message body.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| is:retweet | Deliver only explicit retweets that match a rule. Can also be negated to exclude retweets that match a rule from delivery and only original content is delivered.

This operator looks only for true Retweets, which use X's retweet functionality. Quoted Tweets and Modified Posst which do not use X's retweet functionality will not be matched by this operator.



**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| is:reply | An operator to filter Posts based on whether they are or are not replies to Posts. Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a rule from delivery.

Note that this operator is available for paid premium and enterprise search and is not available in Sandbox dev environments.



**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| is:quote | Delivers only Quote Tweets, or Posts that reference another Post, as identified by the "is\_quote\_status":true in Post payloads. Can also be negated to exclude Quote Tweets.

**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| is:verified | Deliver only Posts where the author is “verified” by X. Can also be negated to exclude Posts where the author is verified.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:mentions | Matches Posts that mention another X user.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:hashtags | Matches Posts that contain a hashtag.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:media | _Available alias_: has:media_link

Matches Posts that contain a media url classified by X. For example, pic.x.com.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:images | Matches Posts that contain a media url classified by X. For example, pic.x.com.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:videos | _Available alias_: has:video_link

Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Vine, Periscope, or Posts with links to other video hosting sites.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:symbols | Matches Posts that contain a cashtag symbol (with a leading ‘$’ character. For example, $tag).  Note that this operator is only available in the `enterprise` search APIs.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | - -### Product overview - -The enterprise-tier Full-archive Search was launched in August 2015, and the premium-tier version was launched in February 2018. These search products enable customers to immediately access any publicly available Post. With Full-archive Search you submit a single query and receive a response in classic RESTful fashion. Full-archive Search implements (up to) 500-Posts-per-response pagination, and supports up to a 60-requests-per-minute (rpm) rate-limit for premium, 120 rpm for enterprise. Given these details, Full-archive Search can be used to rapidly retrieve Posts, and at large scale using concurrent requests. - -Unlike Historical PowerTrack, whose archive is based on a set of Post flat-files on disk, the Full-archive Search Post archive is much like an on-line database. As with all databases, it supports making queries on its contents. It also makes use of an _index_ to enable high-performance data retrieval. With Full-archive search endpoints, the querying language is made up of PowerTrack Operators, and these Operators each correspond to a Post JSON attribute that is indexed. - -Also, like Historical PowerTrack, there are Post attributes that are current to the time a query is made. For example, if you are using Search API to access a Post posted in 2010 today, the user's profile description, account 'home' location, display name, and Post metrics for Favorites and Retweet counts will be updated to today’s values and not what they were in 2010.  - -### Metadata timelines - -Below is a timeline of when Full-archive search endpoint Operators begin matching. In some cases Operator matching began well _after_ a ‘communication convention’ became commonplace on X. For example, @Replies emerged as a user convention in 2006, but did not become a _first-class object_ or _event_ with ‘supporting’ JSON until early 2007. Accordingly, matching on @Replies in 2006 requires an examination of the Post body, rather than relying on the `to:` and `in_reply_to_status_id:` PowerTrack Operators. - -The details provided here were generated using Full-Archive Search (a product of hundreds of searches). This timeline is not 100% complete or precise. If you identify another filtering/metadata “born on date” fundamental to your use-case, please let us know. - -Note that the underlying Search index is subject to being rebuilt. Accordingly, these timeline details are subject to change. - -#### 2006 - -* March 26 - `lang:`. An example of Post metadata being backfilled while generating the Search index. -* July 13 - `has:mentions` begins matching. -* October 6 - `has:symbols`. $cashtags (or symbols) for discussing stock symbols does not become common until early 2009. Until then most usages were probably slang (e.g., $slang). -* October 26 - `has:links` begins matching. -* November 23 - `has:hashtags` begins matching. - -#### 2007 - -* January 30 - First first-class @reply (in\_reply\_to\_user\_id), `reply_to_status_id:` begins matching. -* August 23 - Hashtags emerge as a common convention for organizing topics and conversations. First real use a week later. - -#### 2009 - -* May 15 - `is:retweet`. Note that this Operator starts matching with the ‘beta’ release of official Retweets and its “Via @’ pattern. During this beta period, the Post verb is ‘post’ and the original Post is not included in the payload. -* August 13 - Final version of official Retweets is released with “RT @” pattern, a verb set to ‘share’, and the ‘retweet_status’ attribute containing the original Post (thus approximately doubling the JSON payload size). - -#### 2010 - -* March 6 - `has:geo`, `bounding_box:` and `point_radius:` geo Operators begin matching. -* August 28 - `has:videos` (Until February 2015, this Operator matches on Posts with links to select video hosting sites such as youtube.com, vimeo.com, and vivo.com). - -#### 2011 - -* July 20 - `has:media` and `has:images` begin matching. Native photos officially announced August 9, 2010. - -#### 2014 - -* December 3 - (Approximately) _Some_ [Enhanced URL metadata](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments) with HTML title and description begins in payloads. Enhanced metadata more fully emerged in May 2016. - -#### 2015 - -* February 10 - `has:videos` matches on ‘native’ X videos. -* February 17 - `has:profile_geo`, `profile_country:`, `profile_region:`, `profile_locality:` [Profile Geo](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) Operators begin matching. -* February 17 - `place_country:` and `place:` Post geo Operators begin matching. - -#### 2016 - -* May 1 - [Enhanced URL metadata](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments) more fully available, and was officially announced as part of the [Gnip 2.0 launch in August 2016](https://blog.x.com/2016/gnip-2-is-here). No associated Operators for these metadata with Search APIs. - -#### 2017 - -* February 22 - Poll metadata become available in enriched native format. No associated Operators for these metadata. - -#### 2022 - -* September 27 - All Post objects created since this date have Edited Post metadata available. All Enterprise endpoints that provide Post objects were updated to provide this metadata starting on this date. The edit metadata provided includes edit_history and edit_controls objects. These metadata will not be returned for Posts that were created before September 27, 2022. Currently, there are no Enterprise Operators available that match these metadata.  To learn more about Edit Post metadata, check out the [Edit Posts fundamentals](/x-api/fundamentals/edit-posts) page. - -#### 2022 - -* September 29 - All Post objects created since this date have Edited Post metadata available. All Enterprise endpoints that provide Post objects were updated to provide this metadata starting on this date. The edit metadata provided includes edit_history and edit_controls objects. These metadata will not be returned for Posts that were created before September 27, 2022. Currently, there are no Enterprise Operators available matching these metadata.  To learn more about Edit Post metadata, check out the [Edit Posts fundamentals](/x-api/fundamentals/edit-posts) page. - -### Filtering tips - -Given all the above timeline information, it is clear that there are a lot of details to consider when writing Search APIs filters. There are two key things to consider: - -* Some metadata have ‘born-on’ dates so filters can result in _false negatives_. Such searches include Operators reliant on metadata that did not exist for all of part of the search period. For example, if you are searching for Posts with the `has:images` Operator, you will not have any matches for periods before July 2011. That is because that Operator matches on _native_ photos (attached to a Post using the X user-interface). For a more complete data set of photo-sharing Posts, filters for before July 2011 would need to contain rule clauses that match on common URLs for photo hosting. -* Some metadata has been backfilled with metadata from a time _after_ the X was posted. - -There are several attribute types that are commonly focused on when creating PowerTrack queries: - -* X Profiles -* Original or shared Posts -* Post language classification -* Geo-referencing Posts -* Shared links media - -Some of these have product-specific behavior while others have identical behavior. See below for more details. - -#### X Profiles - -The Search APIs serves historical Posts with the user profile data set as it is at the _time of retrieval_. If you request a Post from 2014, the user’s profile metadata will reflect how it exists at query-time. - -#### Original Posts and Retweets - -The PowerTrack `_is:retweet_` Operator enables users to either include or exclude Retweets. Users of this Operator need to have two strategies for Retweet matching (or not matching) for data before August 2009. Before August 2009, the Post message itself needs to be checked, using exact phrase matching, for matches on the “@RT ” pattern (Actually, if you are filtering on Retweets from between May-August 2009, the “Via @” pattern should be included). For periods after August 2009, the _is:retweet_ Operator is available. - -#### Post language classifications - -For filtering on a Post's language classification, X's historical products are quite different. When the Search archive was built, all Posts were backfilled with the X language classification. Therefore the lang: Operator is available for the entire Post archive. - -#### Geo-referencing Posts - -There are three primary ways to geo-reference Posts: - -* **Geographical references in Post message.** Matching on geographic references in the Post message, while often the most challenging method since it depends on local knowledge, is an option for the entire Post archive. [Here](https://x.com/biz/statuses/28311) is an example geo-referenced match from 2006 for the San Francisco area based on a ‘golden gate’ filter. - -* **Posts geo-tagged by the user.** With the search APIs the ability to start matching on Posts with some Geo Operators started in March 2010, and with others in February 2015: - - * March 6, 2010: `has:geo`, `bounding_box:` and `point_radius:` - * February 17, 2015: `place_country:` and `place:` -* **Account profile ‘home’ location set by the user.** Profile Geo Operators are available in both Historical PowerTrack and the Search APIs. With the Search APIs, these Profile Geo metadata is available starting in February 2015. For Posts posted before Profile Geo metadata became available, the `bio_location:` Operator is available which can be used to match on non-normalized user input. - - -#### Shared links and media - -In March 2012, the expanded URL enrichment was introduced. Before this time, the Post payloads included only the URL as provided by the user. So, if the user included a shortened URL it can be challenging to match on (expanded) URLs of interest. With the Search APIs, these metadata are available starting in March 2012. - -In July 2016, the enhanced URL enrichment was introduced. This enhanced version provides a web site’s HTML title and description in the Post payload, along with Operators for matching on those. These metadata begin emerging in December 2014. - -In September 2016 X introduced ‘native attachments’ where a trailing shared link is not counted against the 140 Post character limit. Both URL enrichments still apply to these shared links. - -Here are when related Search Operators begin matching: - -* 2006 October 26 - `has:links` -* 2011 July 20 - `has:images` and `has:media` -* 2011 August - `url:` with the [Expanded URLs enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments) As early as September 2006 `(url:"spotify.com" OR url:gnip OR url:microsoft OR url:google OR url:youtube)` matches http://x.com/Adam/statuses/16602, even though there is no urls\[\] metadata in twitter_entities and gnip objects. “youtube.com” is an example of message content that, without any urls\[\] metadata, matches url:youtube. -* 2015 February 10 - `has:videos` for native videos. Between 2010/08/28 and 2015/02/10, this Operator matches on Posts with links to select video hosting sites such as youtube.com, vimeo.com, and vivo.com. -* 2016 May 1 - `url_title:` and `url_description:`, based on the [Enhanced URLs enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments), generally available. First Enhanced URL metadata began appearing in December 2014. - -## Frequently asked questions(FAQ) - -### General Search Post API questions - - -There is a known difference between results provided by the counts endpoint and the data endpoint. You may see a discrepancy in your results because the counts endpoint is pre-compliance (meaning that it does not account for things like deleted Posts, scrub geo, etc.) whereas the data endpoint is compliant at the time of delivery and accounts for all compliance events. - - - -There are a few different reasons why this might have happened, including - -1. the Post you expected to see is from a protected account -2. because the data endpoint accounts for all compliance events (meaning that deleted Posts, scrubbed geos, etc. will not be included in the response). - - -This is likely due to a wrong usage of our premium rules & filtering. Please review our documentation [here](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering) and ensure you understand the restrictions around building rules. - - -Yes, there are, including: - -* [Tweepy](http://www.tweepy.org/) \- good for using the standard search/Posts product (Python) -* [X API](https://github.com/geduldig/TwitterAPI) \- good for using the standard Search Post APIs (Python) -* [Search Posts Python](https://github.com/xdevplatform/search-tweets-python) and [Search Posts Ruby](https://github.com/xdevplatform/search-tweets-ruby) \- two good tools that can be used for enterprise (and v2!) Search Post APIs - -All of the libraries that we directly support can be found on our xdevplatform GitHub page: [https://github.com/xdevplatform](https://github.com/xdevplatform). - -There are [other third-party libraries](/resources/fundamentals/authentication#oauth-1-0a-2) that may also be helpful; however, please note that some of these may not work with our premium and enterprise products. - - -Yes. Our data endpoint paginates at either the specified `maxResults` or after 30 days. - -For example, if you have 800 Posts in a given 30 day period, you will have to make two requests to pull the complete results; because the maximum number of Posts that can be returned per request is 500 (`maxResults`). And if you just have 400 Posts in month one, and then 100 Posts in month two, you will also have to use two requests to pull the full results; because pagination takes place after a period of 30 days even if the first request returns less than the specified `maxResults` Posts. - - -Posts are returned in reverse chronological order. For example, the first page of results will show the most recent Posts that match the query, pagination will continue until the results posted dates get to the `fromDate` initially requested. - - -Only the original Post will count for billing purposes. Any subsequent edits will be ignored and not contribute to your overall activity count.  - -`Enterprise` - - -Our enterprise solutions are customized with predictable pricing to meet the needs of your business. Please apply [here](/x-api/enterprise-gnip-2.0/enterprise-gnip) for more information. - - -* Please refer to our enterprise Search Post APIs documentation [here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-search-apis) -* Useful information on rules and filering can be found [here](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#enterprise-operators) -* Useful information for using the data endpoint can be found [here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#data-endpoint) -* Useful information for using the counts endpoint can be found [here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#counts-endpoint) -* A list of available operators can be found [here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators) - - - -Please get in touch with your Account Manager at X who will be able to help you with this. - - - -### Error troubleshooting guide - -**Code 404 - Not Found** - -1. Please ensure you are using the right parameters for each endpoint (e.g. the `buckets`field can only be used with the counts endpoint, not the data endpoint) -2. Please double check the `:product` `:account_name` and `:label` fields are correct. You can find your `:label` field in the GNIP Console (enterprise customers only). - -## API Reference - -### Enterprise search APIs - -There are two enterprise search APIs: - -* 30-Day Search API - provides Tweets posted with the last 30 days. -* Full-Archive Search API - provides Tweets from as early as 2006, starting with the first Tweet posted in March 2006. - -These search APIs share a common design and the documentation below applies to both. Note that for Tweets created starting September 29, 2022, Tweet objects will include Tweet edit metadata that describes its edit history. See the ["Edit Tweets"](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) fundamentals page for more details. - -Below you will find important details needed when integrating with the enterprise search APIs: - -* Methods for requesting Tweet data and counts -* Authentication -* Pagination -* API request parameters and example requests -* API response JSON payloads and example responses -* HTTP response codes - -The enterprise APIs provide low-latency, full-fidelity, query-based access to the Tweet archive. The only difference in the two APIs is the time frame you can search, either the previous 30 days or from as early as 2006. Time frames can be specified with minute granularity. Tweet data is served in reverse chronological order, starting with the most recent Tweet that matches your query. Tweets are available from the search API approximately 30 seconds after being published. - -#### Methods - -The base URI for enterprise search is `https://gnip-api.x.com/search/`. - -| Method | Description | -| :--- | :--- | -| [POST /search/:product/accounts/:account_name/:label](#SearchRequests) | Retrieve Tweets from the past 30 days that match the specified PowerTrack rule. | -| [POST /search/:product/accounts/:account_name/:label/counts](#CountRequests) | Retrieve the number of Tweets from the past 30 days that match the specified PowerTrack rule. | - -Where: - -* `:product` indicates the search endpoint you are making requests to, either `30day` or `fullarchive`. -* `:account_name` is the (case-sensitive) name associated with your account, as displayed at console.gnip.com -* `:label` is the (case-sensitive) label associated with your search endpoint, as displayed at console.gnip.com - -For example, if the TwitterDev account has the 30-Day search product with a label of 'prod' (short for production), the search endpoints would be: - -* Data endpoint: [https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod.json](https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod.json) -* Counts endpoint: [https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod/counts.json](https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod/counts.json) - -Your complete enterprise search API endpoint is displayed at [https://console.gnip.com](https://console.gnip.com). - -Below there are several example requests using a simple HTTP utility called curl. These examples use URLs with `:product`, `:account_name`, and `:label`. To use these examples, be sure to update the URLs with your details. - -#### Authentication - -All requests to the enterprise search APIs must use HTTP _Basic Authentication_, constructed from a valid email address and password combination used to log into your account at [https://console.gnip.com](https://console.gnip.com). Credentials must be passed as the _Authorization_ header for each request. - -#### Request/response behavior - -Using the `fromDate` and `toDate` parameters, you can request any time period that the API supports. The 30-Day search API provides Tweets from the most recent 31 days (even though referred to as the '30-Day' API, it makes 31 days available to enable users to make complete-month requests). The Full-Archive search API provides Tweets back to the very first tweet (March 21, 2006). However, a single response will be limited to the lesser of your specified 'maxResults' or 31 days. If matching data or your time range exceeds your specified maxResults or 31 days, you will receive a 'next' token which you should use to paginate through the remainder of your specified time range. - -For example, say you are using Full-Archive search and want all Tweets matching your query from January 1, 2017 to June 30, 2017. You will specify that full six-month time period in your request using the `fromDate` and `toDate` parameters. The search API will respond with the first 'page' of Tweets, with the number of Tweets matching your `maxResults` parameter (which defaults to 100). Assuming there are more Tweets (and there most likely will be more), the API will also provide a 'next' token that enables you to make a request for the next 'page' of data. This process is repeated until the API does not return a 'next' token. See the next section for more details. - -#### Pagination - -When making both data and count requests it is likely that there is more data than can be returned in a single response. When that is the case the response will include a ‘next’ token. The ‘next’ token is provided as a root-level JSON attribute. Whenever a ‘next’ token is provided, there is additional data to retrieve so you will need to keep making API requests. - -**Note:** The ‘next’ token behavior differs slightly for data and counts requests, and both are described below with example responses provided in the API Reference section. - -##### Data pagination - -Requests for data will likely generate more data than can be returned in a single response. Each data request includes a parameter that sets the maximum number of Tweets to return per request. This `maxResults` parameter defaults to 100 and can be set to a range of 10-500. If your query matches more Tweets than the 'maxResults' parameter used in the request, the response will include a 'next' token (as a root-level JSON attribute). This 'next' token is used in the subsequent request to retrieve the next portion of the matching Tweets for that query (i.e. the next 'page”). Next tokens will continue to be provided until you have reached the last 'page' of results for that query when no 'next' token is provided. - -To request the next 'page' of data, you must make the exact same query as the original, including `query`, `toDate`, and `fromDate` parameters, if used, and also include a 'next' request parameter set to the value from the previous response. This can be utilized with either a GET or POST request. However, the 'next' parameter must be URL encoded in the case of a GET request. - -You can continue to pass in the 'next' element from your previous query until you have received all Tweets from the time period covered by your query. When you receive a response that does not include a 'next' element, it means that you have reached the last page and no additional data is available for the specified query and time range. - -##### Counts pagination - -The 'counts' endpoint provides Tweet volumes associated with a query on either a daily, hourly, or per-minute basis. The 'counts' API endpoint will return a timestamped array of counts for a maximum of a 31-day payload of counts. If you request more than 31 days of counts you will be provided a 'next' token. As with the data 'next' tokens, you must make the exact same query as the original and also include a 'next' request parameter set to the value from the previous response. - -Beyond requesting more than 31 days of counts, there is another scenario when a 'next' token is provided. For higher volume queries, there is the potential that the generation of counts will take long enough to trigger a response timeout. When this occurs you will receive less than 31 days of counts but will be provided a 'next' token in order to continue making requests for the entire payload of counts. **_Important:_** Timeouts will only issue full "buckets" - so 2.5 days would result in 2 full day "buckets". - -##### Additional notes - -* When using a fromDate or toDate in a search request, you will only get results from within your time range. When you reach the last group of results within your time range, you will not receive a 'next' token. -* The 'next' element can be used with any maxResults value between 10-500 (with a default value of 100). The maxResults determines how many Tweets are returned in each response, but does not prevent you from eventually getting all results. -* The 'next' element does not expire. Multiple requests using the same 'next' query will receive the same results, regardless of when the request is made. -* When paging through results using the 'next' parameter, you may encounter duplicates at the edges of the query. Your application should be tolerant of these. - -#### Data endpoint - -##### POST /search/:product/:label - -###### Endpoint pattern: - -This endpoint returns data for the specified query and time period. If a time period is not specified the time parameters will default to the last 30 days. Note: This functionality can also be accomplished using a GET request, instead of a POST, by encoding the parameters described below into the URL. - -##### Data request parameters - -| Parameters | Description | Required | Sample Value | -| :--- | :--- | :--- | :--- | -| query | The equivalent of one PowerTrack rule, with up to 2,048 characters (and no limits on the number of positive and negative clauses).

This parameter should include ALL portions of the PowerTrack rule, including all operators, and portions of the rule should not be separated into other parameters of the query.

**Note:** Not all PowerTrack operators are supported. Supported Operators are listed [HERE](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators). | Yes | (snow OR cold OR blizzard) weather | -| tag | Tags can be used to segregate rules and their matching data into different logical groups. If a rule tag is provided the rule tag is included in the 'matching_rules' attribute.

It is recommended to assign rule-specific UUIDs to rule tags and maintain desired mappings on the client side. | No | 8HYG54ZGTU | -| fromDate | The oldest UTC timestamp (back to 3/21/2006 with Full-Archive search) from which the Tweets will be provided. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute).

_Specified:_ Using only the fromDate with no toDate parameter will deliver results for the query going back in time from now( ) until the fromDate.

_Not Specified:_ If a fromDate is not specified, the API will deliver all of the results for 30 days prior to now( ) or the toDate (if specified).

If neither the fromDate or toDate parameter is used, the API will deliver all results for the most recent 30 days, starting at the time of the request, going backwards. | No | 201207220000 | -| toDate | The latest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in minute granularity and is not inclusive (i.e. 11:59 does not include the 59th minute of the hour).

_Specified:_ Using only the toDate with no fromDate parameter will deliver the most recent 30 days of data prior to the toDate.

_Not Specified:_ If a toDate is not specified, the API will deliver all of the results from now( ) for the query going back in time to the fromDate.

If neither the fromDate or toDate parameter is used, the API will deliver all results for the entire 30-day index, starting at the time of the request, going backwards. | No | 201208220000 | -| maxResults | The maximum number of search results to be returned by a request. A number between 10 and the system limit (currently 500). By default, a request response will return 100 results. | No | 500 | -| next | This parameter is used to get the next 'page' of results as described [HERE](#Pagination). The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. | No | NTcxODIyMDMyODMwMjU1MTA0 | - - - -###### Additional details - -| | | -| :--- | :--- | -| **Available Timeframe** | 30-Day: last 31 days
Full-Archive: March 21, 2006 - Present | -| **Query Format** | The equivalent of one PowerTrack rule, with up to 2,048 characters (and no limits on the number of positive and negative clauses).

**Note:** Not all PowerTrack operators are supported. Refer to [Available operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators) for a list of supported operators. | -| **Rate Limit** | Partners will be rate limited at both minute and second granularity. The per minute rate limit will vary by partner as specified in your contract. However, these per-minute rate limits are not intended to be used in a single burst. Regardless of your per minute rate limit, all partners will be limited to a maximum of 20 requests per second, aggregated across all requests for data and/or counts. | -| **Compliance** | All data delivered via the Full-Archive Search API is compliant at the time of delivery. | -| **Realtime Availability** | Data is available in the index within 30 seconds of generation on the Twitter Platform | - -##### Example data requests and responses - -###### Example POST request - -* Request parameters in a POST request are sent via a JSON-formatted body, as shown below. -* All portions of the PowerTrack rule being queried for (e.g. keywords, other operators like bounding_box:) should be placed in the 'query' parameter. -* Do not split portions of the rule out as separate parameters in the query URL. - -Here is an example POST (using cURL) command for making an initial data request: -```bash - curl -X POST -u "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm"}' -``` -If the API data response includes a 'next' token, below is a subsequent request that consists of the original request, with the 'next' parameter set to the provided token: -```bash - curl -X POST -u "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm", - "next":"NTcxODIyMDMyODMwMjU1MTA0"}' -``` -###### Example GET request - -* Request parameters in a GET request are encoded into the URL, using standard URL encoding. -* All portions of the PowerTrack rule being queried for (e.g. keywords, other operators like bounding_box:) should be placed in the 'query' parameter. -* Do not split portions of the rule out as separate parameters in the query URL. - -Here is an example GET (using cURL) command for making an initial data request: -```bash - curl -u "http://gnip-api.x.com/search/:product/accounts/:account_name/:label.json?query=from%3Atwitterdev&maxResults=500&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm" -``` -###### Example data responses - -Note that for Tweets created starting September 29, 2022, Tweet objects will include Tweet edit metadata that describes its edit history. See the ["Edit Tweets"](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) fundamentals page for more details. - -Below is an example response to a data query. This example assumes that there were more than ‘maxResults’ Tweets available so a 'next' token is provided for subsequent requests. If 'maxResults' or fewer Tweets are associated with your query, no 'next' token would be included in the response. -The value of the 'next' element will change with each query and should be treated as an opaque string. The 'next' element will look like the following in the response body: -```json -{ - "results": - [ - {--Tweet 1--}, - {--Tweet 2--}, - ... - {--Tweet 500--} - ], - "next":"NTcxODIyMDMyODMwMjU1MTA0", - "requestParameters": - { - "maxResults":500, - "fromDate":"201101010000", - "toDate":"201201010000" - } - } -``` -The response to a subsequent request might look like the following (note the new Tweets and different 'next' value): -```json -{ - "results": - [ - {--Tweet 501--}, - {--Tweet 502--}, - ... - {--Tweet 1000--} - ], - "next":"R2hCDbpBFR6eLXGwiRF1cQ", - "requestParameters": - { - "maxResults":500, - "fromDate":"201101010000", - "toDate":"201201010000" - } - } -``` -You can continue to pass in the 'next' element from your previous query until you have received all Tweets from the time period covered by your query. When you receive a response that does not include a 'next' element, it means that you have reached the last page and no additional data is available in your time range. - - -#### Counts endpoint - -##### /search/:stream/counts - -###### Endpoint pattern: - -`/search/fullarchive/accounts/:account_name/:label/counts.json` - -This endpoint returns counts (data volumes) data for the specified query. If a time period is not specified the time parameters will default to the last 30 days. Data volumes are returned as a timestamped array on either daily, hourly (default), or by the minute. - -**Note:** This functionality can also be accomplished using a GET request, instead of a POST, by encoding the parameters described below into the URL. - -##### Counts request parameters - -| Parameters | Description | Required | Sample Value | -| :--- | :--- | :--- | :--- | -| query | The equivalent of one PowerTrack rule, with up to 2,048 characters (and no limits on the number of positive and negative clauses).

This parameter should include ALL portions of the PowerTrack rule, including all operators, and portions of the rule should not be separated into other parameters of the query.

**Note:** Not all PowerTrack operators are supported. Refer to [Available operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators) for a list of supported operators. | Yes | (snow OR cold OR blizzard) weather | -| fromDate | The oldest UTC timestamp (back to 3/21/2006) from which the Tweets will be provided. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute).

_Specified:_ Using only the fromDate with no toDate parameter, the API will deliver counts (data volumes) data for the query going back in time from now until the fromDate. If the fromDate is older than 31 days from now( ), you will receive a next token to page through your request.

_Not Specified:_ If a fromDate is not specified, the API will deliver counts (data volumes) for 30 days prior to now( ) or the toDate (if specified).

If neither the fromDate or toDate parameter is used, the API will deliver counts (data volumes) for the most recent 30 days, starting at the time of the request, going backwards. | No | 201207220000 | -| toDate | The latest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in minute granularity and is not inclusive (i.e. 11:59 does not include the 59th minute of the hour).

_Specified:_ Using only the toDate with no fromDate parameter will deliver the most recent counts (data volumes) for 30 days prior to the toDate.

_Not Specified:_ If a toDate is not specified, the API will deliver counts (data volumes) for the query going back in time to the fromDate. If the fromDate is more than 31 days from now( ), you will receive a next token to page through your request.

If neither the fromDate or toDate parameter is used, the API will deliver counts (data volumes) for the most recent 30 days, starting at the time of the request, going backwards. | No | 201208220000 | -| bucket | The unit of time for which count data will be provided. Count data can be returned for every day, hour or minute in the requested timeframe. By default, hourly counts will be provided. Options: 'day', 'hour', 'minute' | No | minute | -| next | This parameter is used to get the next 'page' of results as described [HERE](#Pagination). The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. | No | NTcxODIyMDMyODMwMjU1MTA0 | - -###### Additional details - -| | | -| :--- | :--- | -| **Available Timeframe** | 30-Day: last 31 days
Full-Archive: March 21, 2006 - Present | -| **Query Format** | The equivalent of one PowerTrack rule, with up to 2,048 characters.

**Note:** Not all PowerTrack operators are supported. Refer to [Available operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators) for a list of supported operators. | -| **Rate Limit** | Partners will be rate limited at both minute and second granularity. The per minute rate limit will vary by partner as specified in your contract. However, these per-minute rate limits are not intended to be used in a single burst. Regardless of your per minute rate limit, all partners will be limited to a maximum of 20 requests per second, aggregated across all requests for data and/or counts. | -| **Count Precision** | The counts delivered through this endpoint reflect the number of Tweets that occurred and do not reflect any later compliance events (deletions, scrub geos). Some Tweets counted may not be available via data endpoint due to user compliance actions. | - -##### Example counts requests and responses - -###### Example POST request - -* Request parameters in a POST request are sent via a JSON-formatted body, as shown below. -* All portions of the PowerTrack rule being queried for (e.g. keywords, other operators like bounding_box:) should be placed in the 'query' parameter. -* Do not split portions of the rule out as separate parameters in the query URL. - -Here is an example POST (using cURL) command for making an initial counts request: -```bash - curl -X POST -u "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day"}' -``` -If the API counts response includes a 'next' token, below is a subsequent request that consists of the original request, with the 'next' parameter set to the provided token: -```bash - curl -X POST -u "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day", - "next":"YUcxO87yMDMyODMwMjU1MTA0"}' -``` - -###### Example GET request - -* Request parameters in a GET request are encoded into the URL, using standard URL encoding -* All portions of the PowerTrack rule being queried for (e.g. keywords, other operators like bounding_box:) should be placed in the 'query' parameter -* Do not split portions of the rule out as separate parameters in the query URL - -Here is an example GET (using cURL) command for making an initial counts request: -```bash - curl -u "http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label/counts.json?query=TwitterDev&bucket=day&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm" -``` -#### Example counts responses - -Below is an example response to a counts (data volume) query. This example response includes a 'next' token, meaning the counts request was for more than 31 days, or that the submitted query had a large enough volume associated with it to trigger a partial response. - -The value of the 'next' element will change with each query and should be treated as an opaque string. The 'next' element will look like the following in the response body: -```json - { - "results": [ - { "timePeriod": "201101010000", "count": 32 }, - { "timePeriod": "201101020000", "count": 45 }, - { "timePeriod": "201101030000", "count": 57 }, - { "timePeriod": "201101040000", "count": 123 }, - { "timePeriod": "201101050000", "count": 134 }, - { "timePeriod": "201101060000", "count": 120 }, - { "timePeriod": "201101070000", "count": 43 }, - { "timePeriod": "201101080000", "count": 65 }, - { "timePeriod": "201101090000", "count": 85 }, - { "timePeriod": "201101100000", "count": 32 }, - { "timePeriod": "201101110000", "count": 23 }, - { "timePeriod": "201101120000", "count": 85 }, - { "timePeriod": "201101130000", "count": 32 }, - { "timePeriod": "201101140000", "count": 95 }, - { "timePeriod": "201101150000", "count": 109 }, - { "timePeriod": "201101160000", "count": 34 }, - { "timePeriod": "201101170000", "count": 74 }, - { "timePeriod": "201101180000", "count": 24 }, - { "timePeriod": "201101190000", "count": 90 }, - { "timePeriod": "201101200000", "count": 85 }, - { "timePeriod": "201101210000", "count": 93 }, - { "timePeriod": "201101220000", "count": 48 }, - { "timePeriod": "201101230000", "count": 37 }, - { "timePeriod": "201101240000", "count": 54 }, - { "timePeriod": "201101250000", "count": 52 }, - { "timePeriod": "201101260000", "count": 84 }, - { "timePeriod": "201101270000", "count": 120 }, - { "timePeriod": "201101280000", "count": 34 }, - { "timePeriod": "201101290000", "count": 83 }, - { "timePeriod": "201101300000", "count": 23 }, - { "timePeriod": "201101310000", "count": 12 } - ], - "totalCount":2027, - "next":"NTcxODIyMDMyODMwMjU1MTA0", - "requestParameters": - { - "bucket":"day", - "fromDate":"201101010000", - "toDate":"201201010000" - } - } -``` -The response to a subsequent request might look like the following (note the new counts timeline and different 'next' value): -```json - { - "results": [ - { "timePeriod": "201102010000", "count": 45 }, - { "timePeriod": "201102020000", "count": 76 }, - .... - { "timePeriod": "201103030000", "count": 13 } - ], - "totalCount":3288, - "next":"WE79fnakFanyMDMyODMwMjU1MTA0", - "requestParameters": - { - "bucket":"day", - "fromDate":"201101010000", - "toDate":"201201010000" - } - } -``` - -You can continue to pass in the 'next' element from your previous query until you have received all counts from the query time period. When you receive a response that does not include a 'next' element, it means that you have reached the last page and no additional counts are available in your time range. - -#### HTTP response codes - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful. The JSON response will be similar to the following: | -| 400 | Bad Request | Generally, this response occurs due to the presence of invalid JSON in the request, or where the request failed to send any JSON payload. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 404 | Not Found | The resource was not found at the URL to which the request was sent, likely because an incorrect URL was used. | -| 422 | Unprocessable Entity | This is returned due to invalid parameters in the query -- e.g. invalid PowerTrack rules. | -| 429 | Unknown Code | Your app has exceeded the limit on connection requests. The corresponding JSON message will look similar to the following: | -| 500 | Internal Server Error | There was an error on the server side. Retry your request using an exponential backoff pattern. | -| 502 | Proxy Error | There was an error on server side. Retry your request using an exponential backoff pattern. | -| 503 | Service Unavailable | There was an error on server side. Retry your request using an exponential backoff pattern. | diff --git a/enterprise-api/enterprise-gnip-2.0/fundamentals/usage.mdx b/enterprise-api/enterprise-gnip-2.0/fundamentals/usage.mdx deleted file mode 100644 index 9793864b5..000000000 --- a/enterprise-api/enterprise-gnip-2.0/fundamentals/usage.mdx +++ /dev/null @@ -1,757 +0,0 @@ ---- -title: Usage API -description: "The Usage API is a free REST API that provides programmatic access and visibility into activity consumption across products for your enterprise account." -sidebarTitle: Usage API -keywords: ["Usage API", "enterprise usage API", "usage tracking", "consumption tracking", "enterprise usage", "API usage enterprise"] ---- - -## Usage API | Twitter API - -### Overview - -`Enterprise` - -It is the most important and _best_ tool for helping to monitor and manage usage across the different APIs under your account. - -**Important Disclaimer:** - -The usage counts returned from the Usage API may not match those on a billing invoice due to trials and other billing adjustments. All numbers are based on deduped activities consumed within a given day (in UTC). - -#### Features - -* Programmatically retrieving usage data that is available in the console.gnip.com UI -* Stream level usage data - provides usage data at the stream level (e.g., dev and prod) in addition to the product level -* Granular and descriptive data - search "requests" are broken out by Full-Archive and 30-Day Search products  -* Historical PowerTrack “days” and “jobs”  - -### Supported APIs - - -Below is a list of the APIs currently supported by the Usage API: - -* PowerTrack API `enterprise` -* 30-Day Search API `enterprise` -* Full-Archive Search API `enterprise` -* Historical PowerTrack `enterprise` - - -### Limitations - -* The Usage API allows you to access usage data since May 1, 2018.  After July 1, 2019 Usage API allows you to access usage data for the **trailing 13 calendar months** - -* You have the ability to access usage data in **three month intervals** defined with a fromDate and toDate - -See below for a request & response: - -```bash -curl -u: \ -"https://gnip-api.x.com/metrics/usage/accounts/.json?bucket=month" -``` -```json -{ - "account": { - "name": "accountnamehere" - }, - "publishers": [ - { - "type": "twitter", - "used": [ - { - "timePeriod": "201805010000", - "activities": 1235, - "searchRequests30Day": 3, - "searchRequestsFullArchive": 19, - "historicalPowertrackDays": 0, - "historicalPowertrackJobs": 0 - }, - { - "timePeriod": "201806010000", - "activities": 23467, - "searchRequests30Day": 0, - "searchRequestsFullArchive": 66, - "historicalPowertrackDays": 0, - "historicalPowertrackJobs": 0 - }, - { - "timePeriod": "201807010000", - "activities": 431, - "searchRequests30Day": 11, - "searchRequestsFullArchive": 4, - "historicalPowertrackDays": 0, - "historicalPowertrackJobs": 0 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 803, - "searchRequests30Day": 20, - "searchRequestsFullArchive": 7, - "historicalPowertrackDays": 0, - "historicalPowertrackJobs": 0 - }, - "products": [ - { - "type": "Historical PowerTrack Subscription", - "used": [ - { - "timePeriod": "201805010000", - "activities": 0, - "days": 0, - "jobs": 0 - }, - { - "timePeriod": "201806010000", - "activities": 0, - "days": 0, - "jobs": 0 - }, - { - "timePeriod": "201807010000", - "activities": 0, - "days": 0, - "jobs": 0 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 0, - "days": 0, - "jobs": 0 - } - }, - { - "type": "PowerTrack", - "used": [ - { - "timePeriod": "201805010000", - "activities": 267 - }, - { - "timePeriod": "201806010000", - "activities": 3 - }, - { - "timePeriod": "201807010000", - "activities": 32 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 59 - }, - "endpoints": [ - { - "type": "PowerTrack 2.0", - "label": "actformat", - "used": [ - { - "timePeriod": "201805010000", - "activities": 0 - }, - { - "timePeriod": "201806010000", - "activities": 0 - }, - { - "timePeriod": "201807010000", - "activities": 0 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 0 - } - }, - { - "type": "PowerTrack Replay 2.0", - "label": "ogformat", - "used": [ - { - "timePeriod": "201805010000", - "activities": 0 - }, - { - "timePeriod": "201806010000", - "activities": 0 - }, - { - "timePeriod": "201807010000", - "activities": 0 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 0 - } - } - ] - }, - { - "type": "Search API (30-Day) 2.0", - "used": [ - { - "timePeriod": "201805010000", - "activities": 10, - "searchRequests30Day": 3 - }, - { - "timePeriod": "201806010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201807010000", - "activities": 23, - "searchRequests30Day": 11 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 42, - "searchRequests30Day": 20 - }, - "endpoints": [ - { - "type": "Search API (30-Day) 2.0", - "label": "ogformat", - "used": [ - { - "timePeriod": "201805010000", - "activities": 10, - "searchRequests30Day": 3 - }, - { - "timePeriod": "201806010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201807010000", - "activities": 21, - "searchRequests30Day": 10 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 39, - "searchRequests30Day": 18 - } - } - ] - }, - { - "type": "Search API (Full-Archive)", - "used": [ - { - "timePeriod": "201805010000", - "activities": 961, - "searchRequestsFullArchive": 19 - }, - { - "timePeriod": "201806010000", - "activities": 23466, - "searchRequestsFullArchive": 66 - }, - { - "timePeriod": "201807010000", - "activities": 379, - "searchRequestsFullArchive": 4 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 706, - "searchRequestsFullArchive": 7 - }, - "endpoints": [ - { - "type": "Search API (Full-Archive)", - "label": "actformat", - "used": [ - { - "timePeriod": "201805010000", - "activities": 1, - "searchRequestsFullArchive": 3 - }, - { - "timePeriod": "201806010000", - "activities": 0, - "searchRequestsFullArchive": 0 - }, - { - "timePeriod": "201807010000", - "activities": 2, - "searchRequestsFullArchive": 1 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 3, - "searchRequestsFullArchive": 1 - } - }, - { - "type": "Search API (Full-Archive)", - "label": "ogformat", - "used": [ - { - "timePeriod": "201805010000", - "activities": 961, - "searchRequestsFullArchive": 16 - }, - { - "timePeriod": "201806010000", - "activities": 23466, - "searchRequestsFullArchive": 66 - }, - { - "timePeriod": "201807010000", - "activities": 379, - "searchRequestsFullArchive": 3 - } - ], - "projected": { - "timePeriod": "201807010000", - "activities": 706, - "searchRequestsFullArchive": 5 - } - } - ] - } - ] - } - ], - "bucket": "month", - "fromDate": "201805010000", - "toDate": "201808010000" -} -``` - -### Sample Payload - -Below is a sample of the payload: - -```bash -{ - "account": { - "name": "gnip-username" - }, - "bucket": "month", - "publishers": [ - { - "type": "automattic", - "used": [ - { - "activities": 0, - "timePeriod": "201603010000" - } - ], - "projected": { - "activities": 0, - "timePeriod": "201603010000" - }, - "products": [ - { - "type": "PowerTrack", - "used": [ - { - "timePeriod": "201603010000", - "activities": 0 - } - ], - "projected": { - "timePeriod": "201603010000", - "activities": 0 - }, - "endpoints": [ - { - "type": "PowerTrack", - "label": "dev", - "used": [ - { - "timePeriod": "201603010000", - "activities": 0 - } - ], - "projected": { - "timePeriod": "201603010000", - "activities": 0 - } - } - ] - } - ] - }, - { - "type": "twitter", - "used": [ - { - "activities": 84, - "searchRequests30Day": 4, - "searchRequestsFullArchive": 0, - "historicalPowertrackDays": 0, - "historicalPowertrackJobs": 0, - "timePeriod": "201603010000" - } - ], - "projected": { - "activities": 0, - "searchRequests30Day": 0, - "searchRequestsFullArchive": 0, - "historicalPowertrackDays": 0, - "historicalPowertrackJobs": 0, - "timePeriod": "201601010000" - }, - "products": [ - { - "type": "Historical PowerTrack 2.0", - "used": [ - { - "timePeriod": "201511010000", - "activities": 11884, - "days": 5, - "jobs": 5 - }, - { - "timePeriod": "201512010000", - "activities": 0, - "days": 0, - "jobs": 0 - }, - { - "timePeriod": "201601010000", - "activities": 0, - "days": 0, - "jobs": 0 - } - ] - }, - { - "type": "PowerTrack", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0 - }, - { - "timePeriod": "201512010000", - "activities": 27456 - }, - { - "timePeriod": "201601010000", - "activities": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0 - }, - "endpoints": [ - { - "type": "PowerTrack", - "label": "devel", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0 - }, - { - "timePeriod": "201512010000", - "activities": 2930 - }, - { - "timePeriod": "201601010000", - "activities": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0 - } - }, - { - "type": "PowerTrack 2.0", - "label": "devel-v2", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0 - }, - { - "timePeriod": "201512010000", - "activities": 24542 - }, - { - "timePeriod": "201601010000", - "activities": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0 - } - }, - { - "type": "PowerTrack 2.0", - "label": "devel-v2-1", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0 - }, - { - "timePeriod": "201512010000", - "activities": 0 - }, - { - "timePeriod": "201601010000", - "activities": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0 - } - } - ] - }, - { - "type": "Search API", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201512010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201601010000", - "activities": 0, - "searchRequests30Day": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0, - "searchRequests30Day": 0 - }, - "endpoints": [ - { - "type": "Search API", - "label": "devel", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201512010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201601010000", - "activities": 0, - "searchRequests30Day": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0, - "searchRequests30Day": 0 - } - } - ] - }, - { - "type": "Search API (30-Day)", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201512010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201601010000", - "activities": 0, - "searchRequests30Day": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0, - "searchRequests30Day": 0 - }, - "endpoints": [ - { - "type": "Search API (30-Day)", - "label": "devel", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201512010000", - "activities": 0, - "searchRequests30Day": 0 - }, - { - "timePeriod": "201601010000", - "activities": 0, - "searchRequests30Day": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0, - "searchRequests30Day": 0 - } - } - ] - }, - { - "type": "Search API (Full-Archive)", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0, - "searchRequestsFullArchive": 0 - }, - { - "timePeriod": "201512010000", - "activities": 0, - "searchRequestsFullArchive": 0 - }, - { - "timePeriod": "201601010000", - "activities": 0, - "searchRequestsFullArchive": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0, - "searchRequestsFullArchive": 0 - }, - "endpoints": [ - { - "type": "Search API (Full-Archive)", - "label": "devel", - "used": [ - { - "timePeriod": "201511010000", - "activities": 0, - "searchRequestsFullArchive": 0 - }, - { - "timePeriod": "201512010000", - "activities": 0, - "searchRequestsFullArchive": 0 - }, - { - "timePeriod": "201601010000", - "activities": 0, - "searchRequestsFullArchive": 0 - } - ], - "projected": { - "timePeriod": "201601010000", - "activities": 0, - "searchRequestsFullArchive": 0 - } - } - ] - } - ] - } - ] -} -``` - -## API reference - -### get-usage - -#### **Methods** - -| Method | Description | -| :--- | :--- | -| [GET /metrics/usage/accounts/{ACCOUNT_NAME}.json](#GETData) | Retrieve usage data | - -Where: - -* :account\_name is the (case-sensitive) name associated with your account, as displayed at console.gnip.com - -#### **Authentication and Rate Limit** - -##### **Authentication** - -All requests to the Usage API require HTTP Basic Authentication, using any of the email/password credentials enabled on your account to log into your account at console.gnip.com or connect to any Gnip stream. - -##### **Rate Limit** - -The Usage API enforces a rate limit of two requests per minute. - -#### **Best Practices & Limitations** - -##### **Data Availability** - -Usage data is based on deduped activities consumed through the last full time period (UTC) that data was processed. Data is generally processed and updated up to the minute, except in cases where Gnip is deploying systems. - -* The Usage API allows you to access usage data since May 1, 2018.  After July 1, 2019 Usage API allows you to access usage data for the **trailing 13 calendar months**.  - -* You have the ability to access usage data in **three month intervals** defined with a fromDate and toDate - -#### **Requesting and Receiving Data** - -The Usage API works by issuing an HTTP GET request with HTTP BASIC-AUTH credentials to the API endpoint for your account. - -##### GET Request: - -Make a GET request to the following endpoint with your user credentials and account name: - -https://gnip-api.x.com/metrics/usage/accounts/:account\_name.json - - -**Additional Parameters** - -| | | -| :--- | :--- | -| bucket | Optional. The unit of time for which usage data will be provided. Usage data can be returned with daily or monthly granularity.

Requests made without a specified bucket will return monthly granularity.

Options: 'month' or 'day' | -| fromDate (YYYYMMDDHHMM) | Optional. Usage data is only available starting from May 1, 2018. The oldest UTC timestamp from which the usage data will be provided. Timestamp is in day granularity and is inclusive (i.e., 201805010000 includes the 0501 day). Requests that contain values other than '0000' for hour and minute granularity will be defaulted to '0000'.

Requests made without a fromDate or toDate will return usage data by month for the current month and include a historical reference for the past two months.

**Please note:** Starting June 1, 2019, you can access the past 13 calendar months of usage data. For example, if it was the 10th of October, you can access usage data back to September 1st of the previous year.
**Example:** 201810010000 will return data starting October 1st, 2018 onward, including October 1st. | -| toDate (YYYYMMDDHHMM) | Optional. The latest UTC timestamp to which the usage data will be provided. Timestamp is in day granularity and is not inclusive (i.e., 201703020000 does not include data for the 0302 day). When a toDate is specified for either the current day or a day in the future, usage data will be returned up to the last full day (UTC). Requests that contain values other than '0000' for hour and minute granularity will be defaulted to '0000'.

A request with no toDate, will default to the next bucket (tomorrow for bucket=day and next month for bucket=month). A request made with no fromDate and toDate will default to bucket=month, and show data for the current month plus the two immediately previous months.

**Example:** 201703050000 will return data to March 5, 2017, not including any data from March 5th. | - - -**Example GET Request** - -This request will return data by month granularity from March 1, 2017 to March 5, 2017, not including any data from March 5, 2017. - -curl -u "https://gnip-api.x.com/metrics/usage/accounts/:account\_name.json?bucket=month&fromdate=201403010000&toDate=201403150000" - - - -#### **Data Format** - -The following tables describe the root-level data structures for usage data returned from the Usage API. For fields with multiple levels of sub-fields, click the links provided to reveal details about the sub-fields. - -If you would like to see an sample of a full Usage API payload, please visit [this page](/x-api/usage/introduction). - -| | | -| :--- | :--- | -| **account** | An object representing the account for which usage data was requested. | -| **bucket** | The unit of time for which usage data is provided. Can be either 'day' or 'month'. | -| **fromDate** | The earliest UTC timestamp for which you want to pull usage data (inclusive). | -| **toDate** | The latest UTC timestamp for which you want to pull usage data (exclusive). | -| **publishers** | Includes three primary objects: Used, projected, and products. | diff --git a/enterprise-api/enterprise-gnip-2.0/powertrack-api.mdx b/enterprise-api/enterprise-gnip-2.0/powertrack-api.mdx deleted file mode 100644 index f7fade9b3..000000000 --- a/enterprise-api/enterprise-gnip-2.0/powertrack-api.mdx +++ /dev/null @@ -1,1982 +0,0 @@ ---- -title: PowerTrack API -keywords: ["PowerTrack", "PowerTrack API", "enterprise PowerTrack", "GNIP PowerTrack", "streaming API", "enterprise streaming"] ---- -This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the ["Edit Posts" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets).  - -## Overview - -[Enterprise](https://developer.x.com/en/products/x-api/enterprise) - -_This is an enterprise API available within our managed access levels only. To use this API, you must first set up an account with our enterprise sales team. [Learn more](https://developer.x.com/en/products/x-api/enterprise)_ - -_You can view all of the X API filtered stream offerings [HERE](/x-api/posts/filtered-stream)._ - -The PowerTrack API provides customers with the ability to filter the full X firehose, and only receive the data that they or their customers are interested in. This is accomplished by applying the PowerTrack filtering language - see [Rules and filtering](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering) \- to match Posts based on a wide variety of attributes, including user attributes, geo-location, language, and many others. Using PowerTrack rules to filter Post ensures that customers receive all of the data, and _only_ the data they need for your app. - - -### Core components - -The PowerTrack API consists of two endpoints: - -#### Rules endpoint - -A separate endpoint managed independently by your application, the rules endpoint supports GET, POST, POST _method=delete and rule validation methods with basic authentication for managing your ruleset. It can support thousands of rules that allow you to filter the realtime stream of data for the topics and conversations that you care about. The rules endpoint can be accessed, managed, and will persist regardless of your connection status to the stream - you can also update (add/remove) rules while connected to the stream and the changes will take effect almost immediately. - -#### Stream endpoint - -Connecting to the streaming endpoint consists of a simple [GET](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-api) request using basic authentication. Once a connection is established, data is delivered in JSON format (see sample payload below) through a persistent HTTP Streaming connection. You will only receive data matching your rules while connected to the stream. - -#### Rule tags - -A single PowerTrack stream can support thousands of rules, so being able to discern which rule(s) matched a given Post becomes important. This is easily solved by using rule tags. Upon rule creation, you can assign a tag value which will be returned in the matching_rules object ([see here](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#matching-rules)) of the response payload. - -Rule tags can represent an end customer use case, a topic or conversation, or another helpful identifier that you can use to route incoming Posts accordingly. - -If, in addition to realtime data, your product also requires instant access to recent data, we recommend using our [Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api). - - -### Available operators - -The PowerTrack API currently supports the following operators: - -* keyword -* emoji -* "exact phrase match" -* "keyword1 keyword2"~N -* contains: -* from: -* to: -* url: -* url_title: -* url_description: -* url_contains: -* has:links -* sample: -* # -* point_radius:\[lon lat radius\] -* bounding\_box:\[west\_long south\_lat east\_long north_lat\] -* @ -* $ -* bio: -* bio_name: -* retweets_of: -* lang: -* bio_location: -* statuses_count: -* followers_count: -* friends_count: -* listed_count: -* is:verified -* source: -* place: -* place_country: -* has:geo -* has:mentions -* has:hashtags -* has:images -* has:videos -* has:media -* has:symbols -* is:retweet -* is:reply -* is:quote -* retweets\_of\_status_id: -* in\_reply\_to\_status\_id: -* has:profile_geo -* profile\_point\_radius:\[long lat radius\] -* profile\_bounding\_box:\[west\_long south\_lat east\_long north\_lat\] -* profile_country: -* profile_region: -* profile_locality: -* profile_subregion: - -For more details, please see the [Getting started with enterprise rules](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#enterprise-operators) guide. - - -### Sample payload - -Below is a sample payload from the PowerTrack API in Native Enriched format: - -``` -{ - "created_at": "Wed Oct 10 20:19:24 +0000 2018", - "id": 1050118621198921700, - "id_str": "1050118621198921728", - "text": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin t… https://t.co/MkGjXf9aXm", - "source": "X Web Client", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 6253282, - "id_str": "6253282", - "name": "X API", - "screen_name": "API", - "location": "San Francisco, CA", - "url": "https://developer.x.com", - "description": "The Real X API. Tweets about API changes, service issues and our Developer Platform. Don't get an answer? It's on my website.", - "translator_type": "null", - "derived": { - "locations": [ - { - "country": "United States", - "country_code": "US", - "locality": "San Francisco", - "region": "California", - "sub_region": "San Francisco County", - "full_name": "San Francisco, California, United States", - "geo": { - "coordinates": [ - -122.41942, - 37.77493 - ], - "type": "point" - } - } - ] - }, - "protected": false, - "verified": true, - "followers_count": 6172196, - "friends_count": 12, - "listed_count": 13003, - "favourites_count": 31, - "statuses_count": 3650, - "created_at": "Wed May 23 06:01:13 +0000 2007", - "utc_offset": null, - "time_zone": null, - "geo_enabled": false, - "lang": "en", - "contributors_enabled": false, - "is_translator": null, - "profile_background_color": "null", - "profile_background_image_url": "null", - "profile_background_image_url_https": "null", - "profile_background_tile": null, - "profile_link_color": "null", - "profile_sidebar_border_color": "null", - "profile_sidebar_fill_color": "null", - "profile_text_color": "null", - "profile_use_background_image": null, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/942858479592554497/BbazLO9L_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/6253282/1497491515", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin tone modifiers 👍🏻👍🏽👍🏿. This is now reflected in Twitter-Text, our Open Source library. \n\nUsing Twitter-Text? See the forum post for detail: https://t.co/Nx1XZmRCXA", - "display_text_range": [ - 0, - 277 - ], - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https://t.co/Nx1XZmRCXA", - "expanded_url": "https://devcommunity.x.com/t/new-update-to-the-twitter-text-library-emoji-character-count/114607", - "display_url": "devcommunity.com/t/new-update-t…", - "unwound": { - "url": "https://devcommunity.x.com/t/new-update-to-the-twitter-text-library-emoji-character-count/114607", - "status": 200, - "title": "New update to the Twitter-Text library: Emoji character count", - "description": "Over the years, we have made several updates to the way that people can communicate on X. One of the more notable changes made last year was to increase the number of characters per Tweet from 140 to 280 characters. Today, we continue to expand people’s ability to express themselves by announcing a change to the way that we count emojis. Due to the differences in the way written text and emojis are encoded, many emojis (including emojis where you can apply gender and skin tone) have count..." - }, - "indices": [ - 254, - 277 - ] - } - ], - "user_mentions": [], - "symbols": [] - } - }, - "quote_count": 0, - "reply_count": 0, - "retweet_count": 0, - "favorite_count": 0, - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https://t.co/MkGjXf9aXm", - "expanded_url": "https://x.com/i/web/status/1050118621198921728", - "display_url": "x.com/i/web/status/1…", - "indices": [ - 117, - 140 - ] - } - ], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en", - "timestamp_ms": "1539202764211", - "matching_rules": [ - { - "tag": null, - "id": 1128017341835464700, - "id_str": "1128017341835464704" - } - ] -} -} -``` -See code examples:  - -* [See simple scripts in several languages to help get started](https://github.com/gnip/support/tree/master/Premium%20Stream%20Connection) -* See an example Java client libraries: [Hosebird Client adapted for enterprise streams](https://github.com/jimmoffitt/hbc), [Gnip4J](https://github.com/zauberlabs/gnip4j) - -* [See an example Python client library](https://github.com/tw-ddis/Gnip-Stream-Collector-Metrics) - -## Guides -### Integrating with PowerTrack - -To integrate PowerTrack into your product, you will need to build an application that can do the following: - -1. Establish a streaming connection to the PowerTrack stream API. -2. Asynchronously send POST requests to the PowerTrack rules API to add and delete rules from the stream. -3. Handle low data volumes – Maintain the streaming connection, and ensure buffers are flushed regularly. -4. Handle high data volumes – de-couple stream ingestion from additional processing using asynchronous processes. -5. Reconnect to the stream automatically when disconnected for any reason. - -For details on the types of requests needed for tasks 1 and 2, and important considerations in implementing them, see the [API reference](/x-api/enterprise-gnip-2.0/powertrack-api#api-reference-index). - -### Rules & Filtering - -PowerTrack enhances the ability to filter X's full firehose, and only receive the data that they or their customers are interested in. This is accomplished by applying PowerTrack filtering language to match Posts based on a wide variety of attributes, including user attributes, geo-location, language, and many others. Using PowerTrack rules to filter a data source ensures that customers receive all of the data, and _only_ the data they need for your app. - -As described, customers add filtering rules to the PowerTrack stream to determine which activities will be sent through the connection. The PowerTrack stream can support thousands of these individual rules, and deliver the combined set of matching activities through the single stream connection. - -The set of PowerTrack rules used to filter a customer’s stream is highly flexible. If a customer needs to add a new filtering rule to capture a different type of content, or remove an existing rule, their app can send a request to the PowerTrack API to make it happen. When that request is sent, the filtering rules are automatically modified and the changes simply take effect in the data stream with no need to reconnect. This allows customers to provide data for many customers at scale, while supporting distinct filtering requirements for each of those customers. - -[See Complete List of Operators »](/x-api/enterprise-gnip-2.0/powertrack-api#available-operators) - -#### Data - -Data is delivered to the customer’s app through a constant stream as it is created. The realtime stream does not provide recent data – rather, it begins filtering for and delivering results based on the time a filtering rule is added to the stream. If, in addition to realtime data, your product also requires instant access to recent data, we recommend using the [Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api). - -Data is in Gzip compressed JSON format. - -#### Matching Rules - -When an activity is delivered through the PowerTrack stream, adds metadata in the [“matching rules”](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#matching-rules) portion of that activity to indicate which rule or rules caused that specific activity to be delivered. If multiple rules match a single activity, the activity is delivered a single time with each of the matching rules included in this metadata. The matching rules provide an easy way to associate a specific activity with specific rules and customers in your product, even where you have many customers with lots of distinct rules. Since the data is delivered through a single stream in this manner, scaling up as your product gains additional customers is simple. - -#### Rule Tags - -At the time they are created, each filtering rule may be created with a tag. Rule tags have no special meaning, they are simply treated as opaque strings carried along with the rule. They will be included in the “matching rules” metadata in activities returned. Tags provide an easy way to create logical groupings of PowerTrack rules. For example, you may generate a unique ID for a specific rule as its tag, and allow your app to reference that ID within activities it processes to associate a result with specific customers, campaigns, categories, or other related groups. - -Note that tags cannot be updated on an existing rule, but can only be included when a rule is created. In order to “update” a tag, you need to first remove the rule, then add it again with the updated tag. The best solution is to simply use a unique identifier as your tag, which your system can associate with various other data points within your own app, all without having to change anything in the rule set. - -PowerTrack API - -### PowerTrack operators - -Below is a list of all operators supported in X's enterprise real-time and historical PowerTrack APIs. - - OperatorDescriptionkeyword -Matches a keyword within the body of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (for example, coca-cola), symbol, or separator characters, you must use a quoted exact match as described below. - -**Note:** This operator will match on both URLs and unwound URLs within a Post.emoji -Matches an emoji within the body of a Post. Emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Post with the text “I like 🍕” would be split into the following tokens: I, like, 🍕. These tokens would then be compared to the emoji used in your rule. Note that if an emoji has a variant, you must use “quotations” to add to a rule. -"exact phrase match" - -Matches an exact phrase within the body of a Post. - -**Note:** In 30 Day Search and Full Archive Search, punctuation is not tokenized and is instead treated as whitespace.  -For example, quoted “#hashtag” will match “hashtag” but not #hashtag (use the hashtag # operator without quotes to match on actual hashtags  -For example, quoted “$cashtag” will match “cashtag” but not $cashtag (use the cashtag $ operator without quotes to match on actual cashtags - -**Note:** This operator will match on both URLs and unwound URLs within a Post. - -# - -Matches any Post with the given hashtag. - -This operator performs an exact match, NOT a tokenized match, meaning the rule “2016” will match posts with the exact hashtag “2016”, but not those with the hashtag “2016election” - -Note: that the hashtag operator relies on X's entity extraction to match hashtags, rather than extracting the hashtag from the body itself. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-entities) for more information on X Entities JSON attributes. - -@ - -Matches any Post that mentions the given username. - -The to: operator returns a subset match of the @mention operator. - -"keyword1 keyword2"~N - -Commonly referred to as a proximity operator, this matches a Post where the keywords are no more than N tokens from each other. - -If the keywords are in the opposite order, they can not be more than N-2 tokens from each other. - -Can have any number of keywords in quotes. - -N cannot be greater than 6. - -**Example:** ********************"snowy mountain resort"~6******************** - -contains: - -Substring match for Posts that have the given substring in the body, regardless of tokenization. In other words, this does a pure substring match and does not consider word boundaries. - -Use double quotes to match substrings that contain whitespace or punctuation. - -from: - -Matches any Post from a specific user. - -The value must be the user’s X numeric Account ID or username (excluding the @ character). See HERE or [HERE](http://gettwitterid.com/) for methods for looking up numeric X Account IDs. - -url: -Performs a tokenized (keyword/phrase) match on the expanded URLs of a Post (similar to url_contains). Tokens and phrases containing punctuation or special characters should be double-quoted. For example, url:"/developer". While generally not recommended, if you want to match on a specific protocol, enclose in double-quotes: url:"https://developer.x.com". - -**Note:** When using PowerTrack or Historical PowerTrack, this operator will match on URLs contained within the original Post of a Quote Tweet. For example, if your rule includes url:"developer.x.com", and a Post contains that URL, any Quote Tweets of that POst will be included in the results. This is not the case when using the Search API.url_title: - -_Available alias_: url_title: - -Performs a keyword/phrase match on the (new) expanded URL HTML title metadata. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#expanded-and-enhanced-urls) for more information on expanded URL enrichment. - -url_description: - -_Available alias_: within\_url\_description: - -Performs a keyword/phrase match on the (new) expanded page description metadata. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#expanded-and-enhanced-urls) for more information on expanded URL enrichment. - -url_contains: - -Matches Posts with URLs that literally contain the given phrase or keyword. To search for patterns with punctuation in them (i.e. google.com) enclose the search term in quotes. - -NOTE: If you’re using the [Expanded URL](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#expanded-and-enhanced-urls) output format, we will match against the expanded URL as well. - -bio: - -_Available alias_: user_bio: - -Matches a keyword or phrase within the user bio of a Post. This is a tokenized match within the contents of the 'description' field within the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object). - -bio_name: -Matches a keyword within the user bio name of a Post. This is a tokenized match within the contents of a user’s “name” field within the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object). -bio_location: - -_Available alias_: user\_bio\_location:  - -Matches posts where the User object's location contains the specified keyword or phrase. This operator performs a tokenized match, similar to the normal keyword rules on the message body. - -This location is part of the [User object](https://developer.x.com/en/docs/x-api/v1/data-dictionary/native-enriched-objects/user), and is the account's 'home' location, is a non-normalized, user-generated, free-form string, and is different from a Post's location (when available).  - -statuses_count: - -_Available alias_: tweets_count: - -Matches Posts when the author has posted a number of statuses that falls within the given range. - -If a single number is specified, any number equal to or higher will match. - -Additionally, a range can be specified to match any number in the given range  (for example, statuses_count:1000..10000). - -followers_count: - -Matches Posts when the author has a followers count within the given range. - -If a single number is specified, any number equal to or higher will match. - -Additionally, a range can be specified to match any number in the given range (for example, followers_count:1000..10000). - -friends_count: - -_Available alias_: following_count:  - -Matches Posts when the author has a friends count (the number of users they follow) that falls within the given range. - -If a single number is specified, any number equal to or higher will match. - -Additionally, a range can be specified to match any number in the given range (for example, friends_count:1000..10000). - -listed_count: - -_Available alias_: user\_in\_lists_count:  - -Matches Posts when the author has been listed on X a number of times falls within the given range. - -If a single number is specified, any number equal to or higher will match. - -Additionally, a range can be specified to match any number in the given range (for example, listed_count:10..100). - -$ - -Matches any Post that contains the specified ‘cashtag’ (where the leading character of the token is the ‘$’ character). - -Note that the cashtag operator relies on X's ‘symbols’ entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-entities) for more information on X Entities JSON attributes. - -retweets_of: - -_Available alias_: retweets\_of\_user: - -Matches Posts that are Retweets of a specified user. Accepts both usernames and numeric X Account IDs (NOT Post status IDs). -See [HERE](/x-api/users/lookup/introduction) for methods for looking up numeric X Account IDs. - -retweets\_of\_status_id: - -_Available alias_: retweets\_of\_tweet_id:  - -Deliver only explicit Retweets of the specified Post. Note that the status ID used should be the ID of an original Post and not a Retweet.  - -in\_reply\_to\_status\_id: - -_Available alias_: in\_reply\_to\_tweet\_id: - -Deliver only explicit replies to the specified Post. - -sample: - -Returns a random sample of Posts that match a rule rather than the entire set of Posts. Sample percent must be represented by an integer value between 1 and 100. This operator applies to the entire rule and requires any “OR’d” terms be grouped. - -**Important Note:** The sample operator first reduces the scope of the firehose to X%, then the rule/filter is applied to that sampled subset. If you are using, for example, **sample:10**, each Post has a 10% chance of being in the sample.  - -Also, the sampling is deterministic, and you will get the same data sample in realtime as you would if you pulled the data historically. - -source:Matches any Post generated by the given source application. The value must be either the name of the application or the application’s URL. **Cannot be used alone.** -lang: - -Matches Posts that have been classified by X as being of a particular language (if, and only if, the post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results. - -**Note:** if no language classification can be made the provided result is ‘und’ (for undefined). - -The list below represents the currently supported languages and their corresponding BCP 47 language identifier: - -| | | | | -| :--- | :--- | :--- | :--- | -| Amharic: am | German: de | Malayalam: ml | Slovak: sk | -| Arabic: ar | Greek: el | Maldivian: dv | Slovenian: sl | -| Armenian: hy | Gujarati: gu | Marathi: mr | Sorani Kurdish: ckb | -| Basque: eu | Haitian Creole: ht | Nepali: ne | Spanish: es | -| Bengali: bn | Hebrew: iw | Norwegian: no | Swedish: sv | -| Bosnian: bs | Hindi: hi | Oriya: or | Tagalog: tl | -| Bulgarian: bg | Latinized Hindi: hi-Latn | Panjabi: pa | Tamil: ta | -| Burmese: my | Hungarian: hu | Pashto: ps | Telugu: te | -| Croatian: hr | Icelandic: is | Persian: fa | Thai: th | -| Catalan: ca | Indonesian: in | Polish: pl | Tibetan: bo | -| Czech: cs | Italian: it | Portuguese: pt | Traditional Chinese: zh-TW | -| Danish: da | Japanese: ja | Romanian: ro | Turkish: tr | -| Dutch: nl | Kannada: kn | Russian: ru | Ukrainian: uk | -| English: en | Khmer: km | Serbian: sr | Urdu: ur | -| Estonian: et | Korean: ko | Simplified Chinese: zh-CN | Uyghur: ug | -| Finnish: fi | Lao: lo | Sindhi: sd | Vietnamese: vi | -| French: fr | Latvian: lv | Sinhala: si | Welsh: cy | -| Georgian: ka | Lithuanian: lt | | - -place: - -Matches Posts tagged with the specified location _or_ X place ID (see examples). Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes. - -**Note:** See the [GET geo/search](https://developer.x.com/en/docs/x-api/v1/geo/places-near-location/api-reference/get-geo-search) public API endpoint for how to obtain X place IDs. - -**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. - -place_country: - -Matches Posts where the country code associated with a tagged [place/location](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-geo-objects) matches the given ISO alpha-2 character code. - -Valid ISO codes can be found here: [http://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - -**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. - -point_radius:\[lon lat radius\] - -Matches against the Exact Location (x,y) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region. - -* Units of radius supported are miles (mi) and kilometers (km). -* Radius must be less than 25mi. -* Longitude is in the range of ±180 -* Latitude is in the range of ±90 -* All coordinates are in decimal degrees. -* Rule arguments are contained within brackets, space delimited. - -**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. - -**Example:** ********************point\_radius:\[2.355128 48.861118 16km\] OR point\_radius:\[-41.287336 174.761070 20mi\]******************** - -bounding\_box:\[west\_long south\_lat east\_long north_lat\] - -_Available alias_: geo\_bounding\_box: - -Matches against the Exact Location (long, lat) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region. - -* west\_long south\_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude. -* east\_long and north\_lat represent the northeast corner of the bounding box, where east\_long is the longitude of that point, and north\_lat is the latitude. -* Width and height of the bounding box must be less than 25mi -* Longitude is in the range of ±180 -* Latitude is in the range of ±90 -* All coordinates are in decimal degrees. -* Rule arguments are contained within brackets, space delimited. - -**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. - -**Example:** ********************bounding_box:\[-105.301758 39.964069 -105.178505 40.09455\]******************** - -profile_country: - -Exact match on the “countryCode” field from the “address” object in the Profile Geo enrichment. - -Uses a normalized set of two-letter country codes, based on ISO-3166-1-alpha-2 specification. This operator is provided in lieu of an operator for “country” field from the “address” object to be concise. - -profile_region: - -Matches on the “region” field from the “address” object in the Profile Geo enrichment. - -This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation. - -profile_locality: - -Matches on the “locality” field from the “address” object in the Profile Geo enrichment. - -This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation. - -profile_subregion: - -Matches on the “subRegion” field from the “address” object in the [Profile Geo](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) enrichment. In addition to targeting specific counties, these operators can be helpful to filter on a metro area without defining filters for every city and town within the region. - -This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation. - -has:geo - -Matches Posts that have Post-specific geolocation data provided from X. This can be either “geo” lat-long coordinate, or a “location” in the form of a X [“Place”](https://dev.x.com/overview/api/places), with the corresponding display name, geo polygon, and other fields. - -**Note:** Operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. - -has:profile_geo - -_Available alias_: has:derived\_user\_geo - -Matches Posts that have any [Profile Geo](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) metadata, regardless of the actual value. - -has:links - -This operator matches Posts which contain links in the message body.is:retweet - -Deliver only explicit retweets that match a rule. Can also be negated to exclude retweets that match a rule from delivery and only original content is delivered. - -This operator looks only for true Retweets, which use X's Retweet functionality. Quoted Tweets and Modified Posts which do not use X's Retweet functionality will not be matched by this operator. - -Can also be negated to match only on original Posts. - -is:quoteDelivers only Quote Tweets, or Posts that reference another Post, as identified by the "is\_quote\_status":true in POst payloads. Can also be negated to exclude Quote Tweets. -is:verified -Deliver only Posts where the author is “verified” by X. Can also be negated to exclude Posts where the author is verified. -is:replyDeliver only replies that match a rule. It can also be negated to exclude delivery of replies that match the specified rule. This operator matches on replies in original Posts, as well as replies in quoted Tweets and Retweets. You can use is:reply in conjunction with is:retweet and is:quote to only deliver replies to original Posts. --is:nullcast - -Negation only. Negates Posts that are nullcasted (for example, contains the ********************"scopes": \{"followers": false}"******************** object). For more info on Nullcasted Posts, [see here](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/guides/tweet-availability). - -Note: Must be used at highest level of rule when used with the Search API.  -Example: (gold AND silver) -is:nullcast - -has:mentions -Matches Posts that mention another X user. -has:hashtags -Matches Posts that contain a hashtag. -has:media - -_Available alias_: has:media_link - -Matches Posts that contain a media URL classified by X. For example, pic.x.com. - -has:images -Matches Posts that contain a media URL classified by X. For example, pic.x.com. -has:videos - -_Available alias_: has:video_link - -Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Vine, Periscope, or Posts with links to other video hosting sites. - -has:symbols -Matches Posts that contain a cashtag symbol (with a leading ‘$’ character. For example, $tag). - - -### Connecting to a streaming endpoint - -Establishing a connection to the streaming APIs means making a very long lived HTTP request, and parsing the response incrementally. Conceptually, you can think of it as downloading an infinitely long file over HTTP. - -**Authentication** - -The following authentication methods are supported by the Streaming APIs: - -| | | | -| :--- | :--- | :--- | -| Auth Type | Supported APIs | Description | -| [OAuth](/resources/fundamentals/authentication) | * Track API Stream | Requests must be authorized [according to the OAuth specification](/resources/fundamentals/authentication) . | -| [Basic auth](/resources/fundamentals/authentication#basic-authentication-3) | * PowerTrack API
* Decahose stream | Requests must use of HTTP Basic Authentication, constructed from a valid email address and password combination. | - -**Connecting** - - -To connect to the Streaming API, form a HTTP request and consume the resulting stream for as long as is practical. Our servers will hold the connection open indefinitely, barring server-side error, excessive client-side lag, network hiccups, routine server maintenance or duplicate logins. - -The method to form an HTTP request and parse the response will be different for every language or framework, so consult the documentation for the HTTP library you are using. - -Some HTTP client libraries only return the response body after the connection has been closed by the server. These clients will not work for accessing the Streaming API. You must use an HTTP client that will return response data incrementally. Most robust HTTP client libraries will provide this functionality. The [Apache HttpClient](http://hc.apache.org/httpcomponents-client-ga/) will handle this use case, for example. - -**Disconnections** - - -X will close a streaming connection for the following reasons: - -* A client establishes too many connections with the same credentials. When this occurs, the oldest connection will be terminated. This means you have to be careful not to run two reconnecting clients in parallel with the same credentials, or else they will take turns disconnecting each other. -* A client stops reading data suddenly. If the rate of Posts being read off of the stream drops suddenly, the connection will be closed. -* A client reads data too slowly. Every streaming connection is backed by a queue of messages to be sent to the client. If this queue grows too large over time, the connection will be closed. -* A streaming server is restarted. This is usually related to a code deploy and is not very frequent. -* X's network configuration changes. These events are rare, and would represent load balancer restarts or network reconfigurations, for example. - -**Stalls** - -Set a timer, either a 90 second TCP level socket timeout, or a 90 second application level timer on the receipt of new data. If 90 seconds pass with no data received, including newlines, disconnect and reconnect immediately according to the backoff strategies in the next section. The Streaming API will send a keep-alive newline every 30 seconds to prevent your application from timing out the connection. You should wait at least 3 cycles to prevent spurious reconnects in the event of network congestion, local CPU starvation, local GC pauses, etc. - -**Reconnecting** - -Once an **established** connection drops, attempt to reconnect immediately. If the reconnect fails, slow down your reconnect attempts according to the type of error experienced: - -* Back off linearly for **TCP/IP level network errors**. These problems are generally temporary and tend to clear quickly. Increase the delay in reconnects by 250ms each attempt, up to 16 seconds. -* Back off exponentially for **HTTP errors** for which reconnecting would be appropriate. Start with a 5 second wait, doubling each attempt, up to 320 seconds. -* Back off exponentially for **HTTP 420 errors**. Start with a 1 minute wait and double each attempt. Note that every HTTP 420 received increases the time you must wait until rate limiting will no longer will be in effect for your account. - -**Connection churn** - -Repeatedly opening and closing a connection (churn) wastes server resources. Keep your connections as stable and long-lived as possible. - -Avoid mobile (cellular network) connections from mobile devices. WiFi is generally OK. - -Delay opening a streaming connection in cases where the user may quit the application quickly. - -If your client works in an environment where the connection quality changes over time, attempt to detect flaky connections. When detected, fall back to REST polling until the connection quality improves. - -**Rate limiting** - -Clients which do not implement backoff and attempt to reconnect as often as possible will have their connections rate limited for a small number of minutes. Rate limited clients will receive HTTP 420 responses for all connection requests. - -Clients which break a connection and then reconnect frequently (to change query parameters, for example) run the risk of being rate limited. - -X does not make public the number of connection attempts which will cause a rate limiting to occur, but there is some tolerance for testing and development. A few dozen connection attempts from time to time will not trigger a limit. However, it is essential to stop further connection attempts for a few minutes if a HTTP 420 response is received. If your client is rate limited frequently, it is possible that your IP will be blocked from accessing X for an indeterminate period of time. - -**Best practices** - -#### Test backoff strategies - -A good way to test a backoff implementation is to use invalid authorization credentials and examine the reconnect attempts. A good implementation will not get any 420 responses. - -#### Issue alerts for multiple reconnects - -If a client reaches its upper threshold of its time between reconnects, it should send you notifications so you can triage the issues affecting your connection. - -#### Handle DNS changes - -Test that your client process honors the DNS Time To live (TTL). Some stacks will cache a resolved address for the duration of the process and will not pick up DNS changes within the proscribed TTL. Such aggressive caching will lead to service disruptions on your client as X shifts load between IP addresses. - -#### User Agent - -Ensure your user-agent HTTP header includes the client’s version. This will be critical in diagnosing issues on X's end. If your environment precludes setting the user-agent field, then set an x-user-agent header. - -**HTTP Error Codes** - -Most error codes are returned with a string with additional details. For all codes greater than 200, clients should wait before attempting another connection. See the Connecting section, above. - -| | | | -| :--- | :--- | :--- | -| Status | Text | Description | -| **200** | **Success** | Self evident. | -| **401** | **Unauthorized** | HTTP authentication failed due to either:

* Invalid basic auth credentials, or an invalid OAuth request.
* Out-of-sync timestamp in your OAuth request (the response body will indicate this).
* Too many incorrect passwords entered or other login rate limiting. | -| **403** | **Forbidden** | The connecting account is not permitted to access this endpoint. | -| **404** | **Unknown** | There is nothing at this URL, which means the resource does not exist. | -| **406** | **Not Acceptable** | At least one request parameter is invalid. For example, the filter endpoint returns this status if:

* The track keyword is too long or too short.
* An invalid bounding box is specified.
* Neither the track nor follow parameter are specified.
* The follow user ID is not valid. | -| **413** | **Too Long** | A parameter list is too long. For example, the filter endpoint returns this status if:

* More track values are sent than the user is allowed to use.
* More bounding boxes are sent than the user is allowed to use.
* More follow user IDs are sent than the user is allowed to follow. | -| **416** | **Range Unacceptable** | For example, an endpoint returns this status if:

* A count parameter is specified but the user does not have access to use the count parameter.
* A count parameter is specified which is outside of the maximum/minimum allowable values. | -| **420** | **Rate Limited** | The client has connected too frequently. For example, an endpoint returns this status if:

* A client makes too many login attempts in a short period of time.
* Too many copies of an application attempt to authenticate with the same credentials. | -| **503** | **Service Unavailable** | A streaming server is temporarily overloaded. Attempt to make another connection, keeping in mind the connection attempt rate limiting and possible DNS caching in your client. | - -### Rule limits - -X will now begin to enforce long-held contractual limits for the number of rules that a customer is able to add to their stream by enforcing rule limits on PowerTrack. While these limits have always been observed, we are now making it easier for customers to know where their limits stand and how close they are to their cap. Functionality has been added to our console that will allow you to observe your current rule count for each product and stream. This information can be found on the right hand side of a product page just under the activity counter (see below). - - - - -This can also be found under the rules section of the usage tab (see below). - - - - -**What If I Hit My Cap?** -If you attempt to upload more rules to your stream that you are contractually allowed, you will receive the following message: - -_“Request exceeds account’s Rule Limit. Delete rules or contact your account manager to proceed.”_ - -If you encounter this error message while you have an open connection, your stream will not be disrupted. In order to add more rules once you hit your cap, you will either need to delete rules from your stream or reach out to your account manager to increase your contractual limit. - - -### Recovery and redundancy features - -#### Introduction - -With streaming high volumes of realtime Posts comes a set of best practices that promote both data reliability and data full-fidelity. When consuming realtime data, maximizing your connection time is a fundamental goal. When disconnects occur, it is important to automatically detect that and reconnect. After reconnecting it’s important to assess if there are any periods to backfill data for. The component that manages these details and consumes realtime Posts is only one part of a system with network, datastore, server, and storage concerns. Given the complexity of these systems, another best practice is to have different streaming environments, with at least separate streams for development/testing and production. - -PowerTrack comes with a set of features that help with these efforts. - -To support multiple environments, we can deploy [Additional Streams](/x-api/enterprise-gnip-2.0/powertrack-api#recovery-and-redundancy-features) for your account. These streams are completely independent of each other, having unique URLs and separate rule sets. - -To help support maintaining a connection, each realtime PowerTrack stream supports [Redundant Connections](/x-api/enterprise-gnip-2.0/powertrack-api#redundant-connections). The most common architecture is for a stream to have two connections, and on the client-side there are two independent consumers, ideally on different networks. With this design, there can be redundancy across the client-side networks, servers, and datastore pathways. Note that a full-copy of the data is served on each connection (since there is a single ‘source’ server and no partitioning with filtered streams) and the client-side must be tolerant of and manage these duplicate data. - -For detecting disconnects, each stream has a ‘heartbeat’ signal that can used to detect when a stream has timed-out. These 10-second heartbeats provide connection confirmation even when there are time periods with no Posts matching your rules and being delivered on your stream. For most X stream consumers, the data volumes are high enough that even a smaller duration of no Posts is a sign of a connection issue. So both a ‘data silence’ and lack of a heartbeat can be used to detect a disconnect. - -Since disconnects will happen, PowerTrack has a dedicated [Recovery](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) and a PowerTrack [Backfill](/x-api/enterprise-gnip-2.0/powertrack-api#backfill) feature to help recover data that was missed due to disconnections and other operational issues. To learn more about disconnects see our support article [HERE](/x-api/enterprise-gnip-2.0/powertrack-api#disconnections-explained). -  - -#### Additional streams  - -Having additional PowerTrack streams is another way to help build reliability into your solution. So much so that it is considered a best practice. Any additional streams are completely independent, having their unique endpoint and independent rule set. Each stream is assigned its own ‘label’, and this label, along with your account name, are part of that stream’s URL. - -https://gnip-stream.x.com/stream/powertrack/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json - -The most common convention is to have a realtime stream dedicated for your production system, and an additional stream available for development and testing. Having a test/development stream enables PowerTrack customers to have a stream to test client consumer updates. While any (unique) label can be assigned to a stream, one convention is to use ‘prod’ for production stream, and ‘dev’ or ‘sandbox’ for an additional development stream. - -The number of streams, and their unique labels, is configurable by your account representative. -  - -#### Redundant connections  - -A redundant connection simply allows you to establish more than 1 simultaneous connections to the data stream. This provides redundancy by allowing you to connect to the same stream with two separate consumers, receiving the same data through both connections. Thus, your app has a hot failover for various situations, e.g. where one stream is disconnected or where your app’s primary server fails. - -The number of connections allowed for any given stream is configurable by your account representative. To use a redundant stream, simply connect to the same URL used for your primary connection. The data for your stream will be sent through both connections, with both stream connections represented on the stream dashboard. - -Note that for billing purposes, we deduplicate the activity counts you receive through multiple connections such that you are only billed for each unique activity once. -  - -#### Recovery  - - -#### Overview  - -Recovery is a data tool that provides streaming access to a rolling window of recent X historical data. It should be utilized to recover data in scenarios where your consuming application misses data in the real time stream, whether due to disconnecting for a short period, or for any other scenario where you fail to ingest realtime data for a period of time. - -There are different varieties of Recovery streams, corresponding to different types of realtime streams that they complement. PowerTrack Recovery streams are provided to allow customers using realtime PowerTrack to recover data they miss, using the same rules as they use in realtime. - -#### Using Recovery  - -With the Recovery stream, your app can make requests to it that operate in the same manner as requests to existing realtime streams. However, your app must specify parameters in the URL that indicate the time window you are requesting. In other words, a Recovery request asks for “Posts from time A to time B.” These Posts are then delivered through your streaming connection in a manner that mimics the realtime stream. - -Posts are delivered beginning with the first minute of the specified time period, continuing until the final minute is delivered. At that point, a “Recovery Request Completed” message is sent through the connection, and the connection is then closed by Gnip. If your request begins at a time of day where little or no matching results occurred, there will likely be some period of time before the first results are delivered – data will be delivered when Recovery encounters matches in the portion of the archive being processed at that time. When no results are available to deliver, the stream will continue sending carriage-return “heartbeats” through the connection to prevent you from timing out. - -Recovery is intended as a tool for easily recovering data missed due to short disconnects, not for very long time periods like entire days. If the need to recover data for long periods arises, we recommend breaking longer requests into shorter time windows (e.g. two hours) to reduce the possibility of being disconnected mid-request due to internet volatility or other reasons, and to provide more visibility into the progress of long requests. - -#### Data availability - -You can use the Recovery feature to recover missed data within the last 24 hours if you are unable to reconnect with the 5 minute backfill window. - -The streaming recovery feature allows you to have an extended backfill window of 24 hours. Recovery enables you to ‘recover’ the time period of missed data. A recovery stream is started when you make a connection request using 'startTime' and 'endTime' request parameters. Once connected, Recovery will re-stream the time period indicated, then disconnect.   - -You will be able to make 2 concurrent requests to recovery at the same time, i.e. “two recovery jobs”. Recovery works technically in the same way as backfill, except a start and end time is defined. A recovery period is for a single time range. - -| Name | Type | Description | -| :--- | :--- | :--- | -| startTime | date (ISO 8601) | YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339).

Date in UTC signifying the start time to recover from. | -| endTime | date (ISO 8601) | YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339).

Date in UTC signifying the end time to recover to. | - -#### Backfill - -The Backfill feature is used to request up to 5 minutes of stream data that is missed after a disconnect, and is available on PowerTrack and Volume streams as an _optional_ feature. - -To request backfill, you need to add a ‘backfillMinutes=number’ parameter to your connection request, where ‘number’ is the number of minutes (1-5, whole numbers only) to backfill when the connection is made. For example, if you disconnect for 90 seconds, you should add ‘backfillMinutes=2’ to your connection request. Since this request will provide backfill for 2 minutes, including for the 30-second period before you disconnected, your _consumer app must be tolerant of duplicate data_. - -An example PowerTrack connection request URL, requesting a 5 minute backfill, looks like: - -https://gnip-stream.x.com/stream/powertrack/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json?backfillMinutes=5 - -**NOTES:** - -* You do have the option to always use ‘backfillMinutes=5’ when you connect, then handling any duplicate data that is provided. - -* If you are disconnected for more than five minutes, you can recover data using the Recovery. -   - - -**Recovering from disconnect** - -Restarting and recovering from a disconnect involves several steps: - -* Determining length of disconnect time period. - * 5 minutes or less? - * If you have Backfill enabled for stream, prepare connection request with appropriate ‘backfillMinutes’ parameter. - * More than 5 minutes? - * Make a connection request using 'startTime' and 'endTime' request parameters in order to start a recovery stream. The streaming recovery feature allows you to have an extended backfill window of 24 hours. Recovery enables you to 'replay' the time period of missed data. -* Request a new connection. - -### Planning for high-volume social data events - -Major national and global events are often accompanied by dramatic spikes in user activity across social media platforms. Sometimes these events are known about in advance, like the Super Bowl, political elections, and New Year’s celebrations around the world. Other times, the spikes in volume are due to unexpected happenings such as natural disasters, unplanned political events, or surprise pop culture moments like Ellen’s famous selfie Post at the Oscars. - -These bursts of user activity can be short-lived (measured in seconds) or they may be sustained over several minutes’ time. No matter their origin, it is important to consider the impact that they can have on applications consuming realtime data from X. - -Here are some best practices that will help your team prepare for high-volume social data events. - -#### Review your current PowerTrack rules - -* Certain keywords can skyrocket during high volume events, for instance brand mentions when a brand sponsors a major sporting event. -* Be careful to avoid any unnecessary or overly generic PowerTrack rules that may generate unnecessary activity volumes. -* Consider communicating with your clients prior to known high-volume events to help them plan appropriately. - -#### Stress test your application - -Anticipate that burst volumes may reach 5-10x average daily consumption levels. Depending on your PowerTrack rule set, the increase may be much higher. - -#### Optimize to stay connected - -With realtime streams, staying connected is essential to avoid missing data. Your client application should be able to detect a disconnect and have logic to immediately retry its connection, using an exponential backoff if the reconnect attempt fails. - -#### Add built-in buffering on your end - -Building a multi-threaded application is a key strategy for handling high-volume streams. At a high-level, a best practice for managing data streams is to have a separate thread/process that establishes the streaming connection and then writes received JSON activities to a memory structure or a buffered stream reader. This ‘light-weight’ stream processing thread is responsible for handling incoming data, which can be buffered in memory, growing and shrinking as needed. Then a different thread consumes that hash and does the ‘heavy lifting’ of parsing the JSON, preparing database writes, or whatever else your application needs to do. - -#### Optional streaming data recovery tools - -* [PowerTrack Replay](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) is available to recover missed activities should you experience an extended disconnection. -* [PowerTrack Backfill](/x-api/enterprise-gnip-2.0/powertrack-api#recovery-and-redundancy-features) automates data recovery if you disconnect briefly. If you disconnect and reconnect within 5 minutes, your data will be buffered by Gnip and delivered automatically. -* If you are unsure whether your Gnip package includes these recovery features, be sure to contact your Account Manager to learn more. - -#### Global events = global time zones - -* The events may occur after business hours or over the weekend, so be sure that your team is prepared for spikes to occur outside your normal business hours. - -#### Don’t Panic! - -* As always, we recommend that you maintain your connections to X real-time APIs and monitor for any changes in delivery latency. -* X's highly-scalable infrastructure ensures that none of your data will be lost or missed from any temporary increases in this latency. - -### Disconnections explained - -Disconnects from your PowerTrack stream can happen for a handful of reasons - whether they proactively planned or unplanned. Regardless of whether or not they were planned, any sort of disconnect can be surprising cause for data loss, but they don’t have to be. A basic understanding of the types of disconnects that you might encounter and how to quickly reconnect can mean the difference between a major issue and something that can be incorporated into your application design by reconnecting, or using Backfill or [Recovery](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api). Please note that for any disconnect, forced or client-side, your [console.gnip.com dashboard](https://console.gnip.com/) will have a message that displays the kind of disconnect that you experienced and a timestamp for the disconnect. - -This article will go over the types of disconnects you might encounter, how to minimize their effects, and how to troubleshoot issues related to disconnects. -  - -#### Forced disconnects - -At the highest level, forced disconnects happen when X actively closes your connection to the stream. These can happen for a variety of reasons, and when you are force disconnected from your stream then X will send a zero byte chunk in accordance with [HTTP chunked encoding practice](http://www.httpwatch.com/httpgallery/chunked/). In all cases of forced disconnects, you should be able to reconnect to the stream immediately and you should be sure to have reconnect logic written into your code to prevent further data loss. - -There are three types of forced disconnects that your app will need to be prepared for. -  - -**X maintenance** - -X deploys for ongoing maintenance several times a week. During these updates, sometimes customer streams will experience one or more disconnects. This will be accompanied by a “X is closing for operational reasons” message. These should be expected disconnections, and your application should be able to reconnect immediately, so make sure that you have reconnect logic written into your application. -  - -**Full buffer disconnect** - -A full buffer disconnect generally indicates that your application’s code isn’t keeping up with the amount of data that we’re streaming to you and there is a backup of cached data on the X server side for your connection which needs to be flushed. This can happen after a major rule change, a [big event](/x-api/enterprise-gnip-2.0/powertrack-api#planning-for-high-volume-social-data-events), or simply because your application is having trouble consuming the stream. Full buffer disconnects are triggered when your stream connection buffer hits a certain threshold of Posts. If you are disconnected for a full buffer, reconnecting with [backfill](/x-api/enterprise-gnip-2.0/powertrack-api#backfill) is not available and data will begin streaming from the time you reconnect. It's likely that you will need to run a [Recovery](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) to recover Posts lost in the disconnection. If you find that full buffer disconnects are happening frequently, reach out to the support team to assist you in making sure that your application is properly configured.  - -Here are some suggestions to prevent these kinds of disconnects from occurring in the future: - -1. Ensure nothing is slowing down the process reading from the stream. Do not do any processing in the process/thread that is reading from the stream. Instead, have this process read the message then pass off any processing (such as parsing, date calculations, etc) of the message to a separate process or thread. -2. Verify there are no network issues between your application and X preventing messages from being sent. -3. Make sure you have sufficient bandwidth for the volume of activities on your stream.  Some streams can have high volumes requiring significant bandwidth (~10 Mbps is not unheard of). Keep in mind these streams require this bandwidth to be sustained 24 hours a day, including spikes that may cause 2-3 times the volume during significant world events. These spikes are often absorbed by X's buffer, and are one of the reasons it is in place. -   - -**Too many connections** - -Each stream is configured to allow for a specified number of connections. This number is determined between you and your account manager, and is available in your account agreement. If you connect to your stream with more connections than are allowed, you will be force disconnected. Any extra connections are allowed for approximately one minute. If after one minute an extra connection exists, the most recent connection is forced disconnected. Allowing an extra connection for a minute enables the customer to, for example, spin up a new server and connect with it, then teardown a server that is being ‘retired.’ -  - -#### Client disconnects - -A client disconnect is essentially any disconnection that occurs which isn’t initiated by our servers. There are many causes for this. Sometimes this could be caused by the code or the architecture of your application, but this often occurs when something in the internet or network layer cuts off the connection. This section provides a list of the most common causes for a client disconnects. -  - -**Issues at the network layer** - -Routing issues at the networking level can cause disconnects. For example, a Border Gateway Protocol (BGP) update can go awry, and clients can disconnect as routers fail to keep up with the sudden additional load put on them when a route fails. As network operators cooperate to reroute traffic, you may notice a pattern of disconnects for some time. -  - -**Firewall configuration** - -Clients may have firewalls set up with session limits that cut off the connections after a certain amount of time, which they need to create exceptions for. From our side, our servers just see the connection close, so we don’t have a way to see whether it was closed by the proactive actions of your app, or just something related to the internet connection between your client and the X servers. -  - -**Data burst and packet loss** - -Clients should be designed to handle spikes in the volume of Posts received. If a client is slow to consume a stream, it will receive a [full buffer disconnect](#full_buffer_disconnect). However, there are situations where the client is not able to handle a sudden surge in volume (for example, after significant rule activity) which will cause the client to drop packets. When this happens, you may notice the client resetting a TCP/IP connection. In certain cases, the connection is terminated correctly and cleanly; however, there may be situations where the underlying networking layer doesn't close the socket properly, or does so after a set delay. In your dashboard, this event will be reported as a client disconnect. In such cases, clients must be sized to handle multiple times the average Post volume. It can be beneficial to examine the network traffic to detect any pattern that leads the client to drop packets. -  - -**Failure to reconnect after a disconnection** - -Occasionally, some customers have trouble reconnecting to their stream after they’ve terminated a connection. Assuming there are no operational issues posted on our [Status Page](https://api.twitterstat.us/), one reason might be that something within your code is keeping the connection alive. In these scenarios, we see something in the layer outside of your app persisting, because the connection wasn’t properly terminated. Generally we see similar behavior when the HTTP client portion of the code isn’t getting proactively closed. It might also be that there is simply some network latency or delay set at the configuration level preventing the request from going through. - - -## Frequently asked questions - -### Realtime PowerTrack API - -**I am interested in X data and would like to find out approximate subscription costs.** - -Please fill out [this form](/x-api/enterprise-gnip-2.0/enterprise-gnip) to get in touch with our Sales team. -  - -**What are some of the features provided by realtime PowerTrack?** - -By connecting directly to our data services, you can take advantage of many enterprise-ready features that provide reliable connectivity and full-fidelity data. As an enterprise licensed-access offering, realtime PowerTrack includes tools for dynamic filtering, consistent connection, data recovery and data compliance management. This technology, paired with operational monitoring, guaranteed support and integration services allows businesses to start with a strong foundation to serve their own customers. - -These features include: - -* Dynamic rule updates while connected to the stream. There is no need to disconnect your stream while you update your stream’s ruleset. -* Support for multiple connections to each stream. -* Ability to automatically recover data that is missed during brief disconnects when you reconnect within 5 minutes with Backfill. -* Availability of Recovery feature to recover missed data within the last 24 hours if you are unable to reconnect with the 5 minute backfill window. -* Availability of additional streams for testing and development. -* Status dashboard to communicate with customers about any operational issues. -   - -**How do I consume streaming data?** - -Realtime streams of data are initiated by sending a HTTP GET command to your custom `https://gnip-stream.x.com` URL. HTTP streaming connections are requested with HTTP headers that indicate a ‘keep-alive’ connection. More information on realtime streaming is available [here](/x-api/enterprise-gnip-2.0/powertrack-api). - -Given the potential of high volumes of X data delivered in a stream, it is highly recommended that incoming data is processed in an asynchronous fashion. What this means is that your code that ‘hosts’ the client side of the stream simply inserts incoming Posts into a (FIFO) queue, or similar memory structure, and then you have a separate process/thread that consumes Posts from that queue and does more of the ‘heavy lifting’ of parsing and preparing the data for storage. With this design, you can implement a process that will bend but not break in case incoming data volumes change dramatically. -  - -**How can multiple customers, projects, and campaigns be managed in a single stream?** - -The vast majority of realtime PowerTrack users manage multiple customers, projects, and campaigns within a single realtime stream by using [PowerTrack rule ‘tags’](/x-api/enterprise-gnip-2.0/powertrack-api). Rule tags have no special meaning, they are simply treated as opaque strings carried along with the rule. They will be included in the “matching rules” metadata in activities returned. - -Tags provide an easy way to create logical groupings of PowerTrack rules. For example, you may generate a unique ID for a specific rule as its tag and allow your application to reference that ID within activities it processes to associate a result with specific customers, campaigns, categories, or other related groups. -  - -**How many connections to a given PowerTrack stream can I have at one time?** - -PowerTrack streams support multiple connections to a single endpoint. Having multiple connections enables customers to build redundant data consumer clients, ideally on different networks. While PowerTrack streams default to a single connection, many customers prefer to have two connections per PowerTrack stream to ensure continuous delivery. If multiple connections are made to a single endpoint, and/or multiple streams exist with common rules, a given Post will be received multiple times. Note that for accounting purposes, the Post will be counted once. - -Please talk to your Account Manager for more information. -  - -**How 'realtime' are the results? Is there any delay/elaboration time between the publication of a Post on X and their release on the PowerTrack stream?** - -Posts that match your ruleset will be delivered to your stream within seconds of being published on the platform. There are variables, such as network connectivity and how your consuming application reads data off the stream; but all things being equal, you should receive Posts within seconds of them being published. - -Please note that the URL enrichment does cause an increased latency, due to the unwinding of each URL in the Post.  - -Generally speaking, you should expect Volume streams (e.g. Firehose and [Decahose](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api)) to be faster than [PowerTrack](/x-api/enterprise-gnip-2.0/powertrack-api), and PowerTrack to be fast than [statuses/filter](https://developer.x.com/en/docs/x-api/v1/tweets/filter-realtime/api-reference/post-statuses-filter). -  - -**Is it possible to update several rules in one go?** - -Yes, you can add or delete several rules with one request. - -However, note that the add and delete steps are separate and you will need two requests: one request to add one or several rule(s) and another request to delete one or several rule(s). - -The upper limit number of rules that can either be added or be deleted in one go is a JSON body that is 5MB or less in size. Depending on the length of your rule values and tags, the upper number will be in the lower thousands. -  - -**Why isn't my rule appearing on the stream right away?** - -Most rule additions take effect almost immediately. However, depending on factors such as network connectivity and rule size/complexity, it may take up to 5 minutes before you start receiving matching Posts. -  - -**What if some Posts are missing: I was expecting them to be returned by the stream, but they weren't?** - -You can follow the next few steps to understand why some Posts might not have been delivered: - -1. Check your [rule](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#enterprise-operators) and ensure that you are using the correct operators. -2. Were you connected to the stream when the Post was created? You can use the 'Connections' tab in the [console](https://console.gnip.com) to check your connection history. -3. Was your rule already in place when the Post was created? -4. Note that if the account from which the Post was sent was private at the time the Post was created, the Post won't be returned - even if the account is public at the time of the request. - - -**If I lose the connection to the stream and then connect back, will I lose all Posts from that duration?** - -Yes, if you lose the connection to the stream, you may be missing data for the period of time that you were disconnected from the stream. Whenever a disconnection occurs, your client app must restart the process by establishing a new connection. - -Additionally, to ensure that you do not miss any data, you may need to utilize a [Redundant Connection](/x-api/enterprise-gnip-2.0/powertrack-api#redundant-connections), [Backfill](/x-api/enterprise-gnip-2.0/powertrack-api#backfill), or a [Replay stream](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) to mitigate or recover data from disconnections from the stream. Please see our answer to the next question for more information. -  - -**What if I get disconnected from the stream? How can I collect any data that was missed while disconnected?** - -When streaming data, the goal is to stay connected for as long as possible, recognizing that disconnects will occur. PowerTrack streams provide a 15-second heartbeat (in the form of a new-line character) that enable client applications to detect disconnects. When fresh data and the heartbeat stop arriving, reconnection logic should be triggered. In most software languages this can be easily implemented by setting a data read timeout. - -Any time you disconnect from the stream, you are potentially missing data that would have been sent if connected. However, there are multiple ways to mitigate these disconnects and recover data when they occur. - -There is a range of tools available for retrieving historical posts, including: - -1. [Redundant Streams](/x-api/enterprise-gnip-2.0/powertrack-api#redundant-connections) \- With multiple connections, consume the stream from multiple servers to prevent missed data when one is disconnected. -2. [Recovery](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) \- Recover data within the last 24 hours. -3. [Backfill](/x-api/enterprise-gnip-2.0/powertrack-api#backfill) \- Reconnect within 5 minutes and start from where you left off. -4. [Full Archive Search](/x-api/enterprise-gnip-2.0/fundamentals/search-api#getting-started-with-enterprise-search-posts-full-archive-api) \- Recover data from the entire X archive. - - -Please also refer to [our documentation on disconnects](/x-api/enterprise-gnip-2.0/powertrack-api#disconnections-explained). -  - -**How fast is the streaming speed of Recovery?** - -Recovery will deliver up to 1000 posts per second. It is intended to deliver the posts for the period of time that a customer is disconnected. - -**Do you have any realtime PowerTrack code examples I can use to get started with?** - -Yes, we have several realtime code examples available, including: - -* [Sample Python scripts](https://github.com/xdevplatform/enterprise-scripts-python) -* [Sample Ruby scripts](https://github.com/xdevplatform/ruby-enterprise-scripts/tree/master/PowerTrack) - -Note that these are only available to enterprise customers. - -** -How do Edit Posts impact my usage and billing? ** - -Only the original Post will count for billing purposes. Any subsequent edits will be ignored and not contribute to your overall activity count.  - -### Error troubleshooting guide - -**Code 429 - Rate Limited: Your app has exceeded the limit on requests to add, delete, or list rules for this stream** - -You may be receiving the 429 error code because you are adding or deleting rules too quickly. If you are adding or deleting rules individually, this could add up and exceed the rate limit. - -A workaround could be to add or delete several rules at one time. - -For example, the below sample cURL command shows you how to delete several rules at once: - - ```bash - curl -v -X POST -uexample@customer.com "https://gnip-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json?_method=delete" -d '{"rule_ids":[734938587381145604,734938587381174273]}" -``` - -You can learn more about adding or deleting rules and the relevant rate limits [here](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-rules-api). -  - -**Code 400** - -A 400 error code normally indicates that the server was unable to process the request sent by the client due to poorly formatted JSON. - -There are many reasons why this might be the case and you will need to double check the format of your JSON query. - -For example, you may need to escape the quotes around the exact phrase match(es) in your rule (as in the example below): - -``` -{"rules":\[{"tag":"test1","value":"coffee OR \\"I love coffee\\""}\]} -``` - -** -Frequent Disconnects - I am experiencing frequent disconnections on the stream and one of the following messages is being returned. Why is this happening?** - -`This stream has been disconnected because your client was unable to keep up with us.` - -`This stream has been disconnected for operational reasons.` - -This kind of error occurs when your stream is not keeping up with the speed at which we are delivering data and your app isn't consuming the data from the stream fast enough. - -We allow delivery to get behind for a period of time, and we have a temporary staging buffer amount for each stream on our side; but if you don't catch up, we initiate a disconnect to allow you to reconnect at the current point in time. Please note that this may lead to data loss (for data that is within the buffer at the time of the full buffer disconnect). - -These can occur around large spikes in data. Generally, we recommend using a buffer process for consuming data quickly that is separate from the processing process. - -You can find out more about optimizing your app to prevent disconnects like this in our articles on [connection](/x-api/enterprise-gnip-2.0/powertrack-api#disconnections-explained) and on consuming streaming data [here](/x-api/enterprise-gnip-2.0/powertrack-api#planning-for-high-volume-social-data-events). - -## API reference index - -For the complete reference, select an API from the list: - -| | | -| :--- | :--- | -| **Add or delete rules from your stream** | [PowerTrack Rules API](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-rules-api) | -| **Connect to your PowerTrack stream** | [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-api)` | -| **Recover Posts lost during an outage** | [Replay API](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) | - - -### PowerTrack API -Jump to on this page - -[Methods](#Methods) - -[Authentication](#Authentication) - -[GET /track/:stream](#Stream) - -#### Methods[](#methods- "Permalink to this headline") - - -| Method | Description | -| :--- | :--- | -| [GET /track/:stream](#Stream) | Connect to the data stream | - -#### Authentication[](#authentication- "Permalink to this headline") - -All requests to the PowerTrack API must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. Make sure your client is adding the "Authentication: Basic" HTTP header (with encoded credentials over HTTPS) to all API requests. - -#### GET /track/:stream[](#get-track-stream- "Permalink to this headline") - -Establishes a persistent connection to the PowerTrack data stream, through which the social data will be delivered. - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **Connection Type** | Keep-Alive

This should be specified in the header of the request. | -| **URL** | Found on the stream's API Help page of your console dashboard, and resembles the following structure:


[https://gnip-stream.x.com/stream/powertrack/accounts/](https://gnip-stream.x.com/stream/powertrack/accounts/){gnip_account_name}/publishers/twitter/{stream_label}.json | -| **Compression** | Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following:

Accept-Encoding: gzip | -| **Character Encoding** | UTF-8 | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | 60 requests per minute. | -| **Read Timeout** | Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds. | -| **Support for Tweet edits** | All Tweet objects will include Tweet edit metadata describing the Tweet's edit history. See the ["Edit Tweets" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) for more details. | - -#### Responses - -The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | Success | The connection was successfully opened, and new activities will be sent through as they arrive. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 406 | Not Acceptable | Generally, this occurs where your client fails to properly include the headers to accept gzip encoding from the stream, but can occur in other circumstances as well.

Will contain a JSON message similar to "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end." | -| 429 | Rate Limited | Your app has exceeded the limit on connection requests. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support or emergency if unable to connect after 10 minutes. | - - - -**Example curl Request** - -The following example request is accomplished using cURL on the command line. However, note that these requests may also be sent with the programming language of your choice. -``` -curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/powertrack/accounts/:account\_name/publishers/twitter/:stream\_label.json" -``` - -### Replay API - - -Jump to on this page - -[Methods](#Methods) - -[Authentication](#Authentication) - -[GET /replay](#Stream) - -#### Methods[](#methods- "Permalink to this headline") - - -| Method | Description | -| :--- | :--- | -| [GET /replay/:stream_type](#Stream) | Connect to the replay stream. For realtime PowerTrack, the Stream Type is 'powertrack'. For Volume Streams, Stream Types include 'sample10' (i.e. decahose), 'firehose', 'mentions', and 'compliance'. | - -#### Authentication[](#authentication- "Permalink to this headline") - -All requests to the Replay API must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. - -#### GET /replay[](#get-replay- "Permalink to this headline") - -Establishes a connection to the Replay data stream. Tweet data will be delivered for the time period specified, and user profile objects will reflect the referenced users at the time when the Replay API is running. - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **Connection Type** | Keep-Alive

This should be specified in the header of the request. | -| **URL** | Found on the stream's API Help page of your dashboard, the URL is built with Stream Type, Account Name and Stream Label tokens. For realtime PowerTrack, the Stream Type is 'powertrack'. For Volume Streams, Stream Types include 'sample10' (i.e. decahose), 'firehose', 'mentions', and 'compliance'.

Replay URLs have the following pattern:


[https://gnip-stream.gnip.com/replay/](https://gnip-stream.gnip.com/replay/){STREAM_TYPE}/accounts/{ACCOUNT_NAME}/publishers/twitter/{STREAM_LABEL}.json


For example, the Replay URL for realtime PowerTrack has the following pattern:


[https://gnip-stream.gnip.com/replay/powertrack/accounts/](https://gnip-stream.gnip.com/replay/powertrack/accounts/){ACCOUNT_NAME}/publishers/twitter/{STREAM_LABEL}.json


For example, the Replay URL for Decahose has the following pattern:


[https://gnip-stream.gnip.com/replay/sample10/accounts/](https://gnip-stream.gnip.com/replay/sample10/accounts/){ACCOUNT_NAME}/publishers/twitter/{STREAM_LABEL}.json | -| **Compression** | Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following:

Accept-Encoding: gzip | -| **Character Encoding** | UTF-8 | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | 5 requests per 5 minutes. | -| **fromDate** | The oldest (starting) UTC timestamp from which the activities will be provided, must be in 'YYYYMMDDHHMM' format. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute). Valid times must be within the last 5 days, UTC time, and no more recent than 31 minutes before the current point in time. It's recommended that the fromDate and toDate should be within ~2 hours. | -| **toDate** | The latest (ending) UTC timestamp to which the activities will be provided, must be in 'YYYYMMDDHHMM' format. Timestamp is in minute granularity and is exclusive (i.e. 12:30 does not include the 30th minute of the hour). Valid times must be within the last 5 days, UTC time, and no more recent than 30 minutes before the current point in time. It's recommended that the fromDate and toDate should be within ~2 hours. | -| **Read Timeout** | Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds. | -| **Support for Tweet edits** | Since all Replay requests are for Tweets posted at least 30 minutes ago, all Tweets returned by Replay will reflect their final edit state. All Tweet objects will include metadata that describes its edit history. See the ["Edit Tweets" fundamentals](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) page for more details. | - - - -#### Responses - -The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | Success | The connection was successfully opened, and new activities will be sent through until the end of the requested time period is reached, and a "Replay Request Completed" message is sent. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 406 | Not Acceptable | Generally, this occurs where your client either fails to properly include the headers to accept gzip encoding from the stream, or specifies an unacceptable fromDate or toDate.

Will contain a JSON message indicating the issue -- e.g. "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end." or "Invalid date for query parameter 'toDate'. Can't ask for tweets from within the past 30 minutes." | -| 429 | Rate Limited | Your app has exceeded the limit on connection requests. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support. | - - - -#### "Request Completed" Message - -Once a request has been completed, a "Replay Request Completed" message will be delivered through the stream prior to disconnecting inside a "info" JSON message. If your stream is disconnected prior to receiving this message, the request was not completed, and you will need to re-run the missing portion of the request. - -A premature disconnection may occur especially where your client is not consuming activities quickly enough. In this scenario, the connection may send the "Completed" message, but the connection may close prior to your client receiving it due to the slow rate of consumption. In this scenario, your client should re-request the end-portion of the data to ensure completeness, based on the timestamps of the last Tweets received. - -The "info" JSON message has the following structure: - -``` -{ - "info": { - "message": "Replay Request Completed", - "sent": "2016-05-27T22:15:50+00:00", - "activity_count": 8874 - } -} -``` -If any errors are associated with a completed Replay request, the "info" message will indicate that errors occurred and also list the minutes that were effected in the "minutes_failed" field. Here is an example: -``` -{ - "info": { - "message": "Replay Request Completed with Errors", - "sent": "2016-05-27T16:00:02+00:00", - "activity_count": 56333, - "minutes_failed": \[ - "2013-02-20T00:05:00+00:00", - "2013-02-20T00:06:00+00:00" - \] - } -} -``` -Users (or their client applications) should monitor for complete success of the Replay stream, and submit new Replay requests for any minutes that failed. - -#### "Request Failed to Complete" Message - -If a Replay request fails to complete, the "info" message will indicate the failure and also list the time range was was not processed. Here is an example: -``` -{ - "info": { - "message": "Replay Request Failed to Complete", - "sent": "2016-06-27T16:37:13+00:00", - "unprocessed_range": { - "fromDate": "2016-06-26T00:00:00+00:00", - "toDate": "2016-06-26T00:01:00+00:00" - }, - "activity_count": 1822 - } -} -``` -If this message is received another Replay request should be made based on the "fromDate" and "toDate" included in the "unprocessed_range" attribute. - -#### Example curl Request - -The following example request is accomplished using cURL on the command line, and requests the first hour of data from June 1, 2016. -``` -curl --compressed -v -uexample@customer.com "https://gnip-stream.gnip.com/replay/powertrack/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}json?fromDate=201606010000&toDate=201606010100" -``` - -#### Sample streams Replay Examples (Stream Types include 'sample10' (i.e. decahose), 'firehose', 'mentions')[](#sample-streams-replay-examples-stream-types-include-sample10-i-e-decahose-firehose-mentions- "Permalink to this headline") - -Decahose, firehose, mentions note- All partitions from volume streams are delievered in a single Replay connection. -``` -curl --compressed -v -uexample@customer.com -"https://gnip-stream.gnip.com/replay/sample10/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json?fromDate=201712312330&toDate=201801010130" -``` - -#### Compliance Replay Examples[](#compliance-replay-examples "Permalink to this headline") - -Compliance note- All partitions from Compliance Firehose are delievered in a single Replay connection. -``` -curl --compressed -v -uexample@customer.com -"https://gnip-stream.gnip.com/replay/compliance/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json?fromDate=201712312330&toDate=201801010130" -``` -### PowerTrack Replay Examples[](#powertrack-replay-examples "Permalink to this headline") - -Connection to Replay to complete data during the 2018 New Year's eve disconnection: - -``` -curl --compressed -v -uexample@customer.com -"https://gnip-stream.gnip.com/replay/powertrack/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json?fromDate=201712312330&toDate=201801010130" -``` - -Important Note: When using PowerTrack Replay, you must first add or manage the rules currently on the replay stream. PowerTrack rules are not automatically added to a Replay stream from a normal PowerTrack stream. Rules can be managed through the Rules API for a Replay stream. Please see the [PowerTrack Rules API](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-rules-api) for specific details on managing rules. - -Rules management on the PowerTrack replay: -``` -curl -v -X POST -uexample@customer.com -"https://gnip-api.x.com/rules/powertrack-replay/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json" --d '{"rules":\[{"value":"rule1","tag":"tag1"},{"value":"rule2"}\]}' -``` - -### PowerTrack Rules API - - -Jump to on this page - -[Methods](#Methods) - -[Authentication](#Authentication) - -[POST /rules](#AddRules) - -[GET /rules](#ListRules) - -[GET /rules/:rule_id](#GetRule) - -[POST /rules _method=get](#GetRules) - -[POST /rules _method=delete](#DeleteRules) - -[POST /validation](#ValidateRules) - -#### Methods[](#methods- "Permalink to this headline") - - -| Method | Description | -| :--- | :--- | -| [POST /rules](#AddRules) | Add rules to the stream | -| [GET /rules](#ListRules) | Retrieve all rules currently in place on the stream | -| [GET /rules/:rule_id](#GetRule) | Retrieve an existing rule on the stream by rule ID | -| [POST /rules _method=get](#GetRules) | Retrieve multiple rules on the stream by rule IDs | -| [POST /rules _method=delete](#DeleteRules) | Delete rules from the stream | -| [POST /validation](#ValidateRules) | Validate PowerTrack rule syntax | - -#### Authentication[](#authentication- "Permalink to this headline") - -All requests to the PowerTrack rules API must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. Make sure your client is adding the "Authentication: Basic" HTTP header (with encoded credentials over HTTPS) to all API requests. - -#### POST /rules[](#post-rules- "Permalink to this headline") - - -Adds one or many rules to your PowerTrack stream's ruleset. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **Content Type** | "application/json". The request should specify this as the "Content-type". | -| **URL** | Found on the [Console - Products API Help tab](/x-api/enterprise-gnip-2.0/fundamentals/overview#products-tab), and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json` | -| **Character Encoding** | UTF-8 | -| **Request Body Format** | JSON | -| **Request Body Size Limit** | 5 MB | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). Rule addition requests will be processed serially and will be rejected if you have more than one rule request happening at the same time. | - - - -#### Request Body Content - -Your request should provide rule data in the following format with the defined Content-type: "application/json": -``` - { - "rules": - [ - {"value":"rule1","tag":"tag1"}, - {"value":"rule2","tag":"tag2"} - ] - } -``` - - -**Example curl Request** - -The following example requests demonstrate how to add rules using cURL on the command line, using JSON rules. -``` - curl -v -X POST -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json" -d '{"rules":[{"value":"rule1","tag":"tag1"},{"value":"rule2","tag":"tag2"}]}' -``` - -``` - curl -v -X POST -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json" -d @arrayofrulesfile_max5mb.json -``` - -``` - curl -v -X POST -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/companyname/publishers/twitter/prod.json" -d '{"rules":[{"value":"(#snow OR snowday OR "snow day" OR from:noaa) lang:en","tag":"4581245"},{"value":"(skiing OR boarding OR "hitting the slopes" OR from:OnTheSnow) lang:en","tag":"4581267"}]}' -``` - - -#### Responses - -The following responses may be returned by the API for these requests. Non-200 responses should be retried after making any necessary modifications in the rules. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 201 | Created | The rule or rules were successfully added to your PowerTrack ruleset. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 422 | Unprocessable Entity | Generally occurs due to an invalid rule, based on the PowerTrack rule restrictions. Requests fail or succeed as a batch. For these errors, each invalid rule and the reason for rejection is included in a JSON message in the response. Catch the associated exception to expose this message. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/) contact support or contact emergency if still unable to connect after 10 minutes. | - - - -**Example Responses** - -This response indicates that all rules (two in this case) were successfully created. -``` - HTTP/1.1 201 Created - { - "summary": { - "created": 2, - "not_created": 0 - }, - "detail": [{ - "rule": { - "value": "(#snow OR snowday OR \"snow day\" OR from:noaa) lang:en", - "tag": "4581245", - "id": 734938587381145604 - }, - "created": true - }, { - "rule": { - "value": "(skiing OR boarding OR \"hitting the slopes\" OR from:OnTheSnow) lang:en", - "tag": "4581267", - "id": 734938587381174273 - }, - "created": true - }], - "sent": "2016-05-24T02:46:28.402Z" - } -``` -This response indicates that one rule was successfully created, and two were not created because they already exist. Rules are indexed by rule value (syntax). For rules not created there is a 'message' field explaining why the rule could not be created. -``` - HTTP/1.1 201 Created - { - "summary": { - "created": 1, - "not_created": 2 - }, - "detail": [{ - "rule": { - "value": "robot OR 🤖", - "tag": "botrule123", - "id": 734861971116285952 - }, - "created": true - }, { - "rule": { - "value": "fish OR 🐟", - "tag": "fishrule123" - }, - "created": false, - "message": "A rule with this value already exists" - }, { - "rule": { - "value": "Pizza OR 🍕", - "tag": "pizzarule123" - }, - "created": false, - "message": "A rule with this value already exists" - }], - "sent": "2016-05-23T21:42:01.661Z" - } -``` -The following responses indicate that no rules were created. In each case there is a 'message' field explaining why the rule could not be created. Note that when one or more rules are invalid, no rules are added (even rules with valid syntax). - - -``` - HTTP/1.1 422 Unprocessable Entity - { - "summary": { - "created": 0, - "not_created": 2 - }, - "detail": [{ - "rule": { - "value": "streaming gnip contains:$twtr", - "tag": null - }, - "created": false, - "message": "no viable alternative at input '$twtr' (at position 25)\n" - }, { - "rule": { - "value": "streaming gnip contains:\"$twtr\"", - "tag": null - }, - "created": false - }], - "sent": "2016-06-01T15:41:27.451Z" - } -``` - -``` - HTTP/1.1 422 Unprocessable Entity - { - "summary": { - "created": 0, - "not_created": 1 - }, - "detail": [{ - "rule": { - "value": "-follow", - "tag": null - }, - "created": false, - "message": "Rules must contain a non-negation term (at position 1)\nRules must contain at least one positive, non-stopword clause (at position 1)\n" - }], - "sent": "2016-05-23T18:34:25.218Z" - } -``` - -``` - HTTP/1.1 422 Unprocessable Entity - { - "summary": { - "created": 0, - "not_created": 1 - }, - "detail": [{ - "rule": { - "value": "streaming AND lang:en", - "tag": null - }, - "created": false, - "message": "Ambiguous use of and as a keyword. Use a space to logically join two clauses, or \"and\" to find occurrences of and in text (at position 11)\n" - }], - "sent": "2016-05-23T21:39:49.612Z" - } -``` - - -#### GET /rules[](#get-rules- "Permalink to this headline") - -Retrieve all rules currently in place on the stream - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **URL** | Found on the [Console - Products API Help tab](/x-api/enterprise-gnip-2.0/fundamentals/overview#products-tab), and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json` | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | - - - -**Example cURL Request** - -The following example request demonstrates how to retrieve rules using cURL on the command line. - - curl -v -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json" - -#### Response - -The following responses may be returned by the API for these requests. Non-200 responses should be retried, utilizing an exponential backoff for subsequent requests. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful, and the current ruleset is returned in JSON format. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/) contact support. | - - - -**Example Response** -``` - HTTP/1.1 200 OK - { - "rules": [{ - "value": "from:xdevelopers", - "tag": "tweetsfromxdevelopers", - "id": 735163830813134848 - }, { - "value": "fish OR 🐟", - "tag": "fishrule123", - "id": 738034522583769088 - }, { - "value": "Pizza OR 🍕", - "tag": "pizzarule123", - "id": 738034522579554304 - }, { - "value": "robot OR 🤖", - "tag": "botrule123", - "id": 738034522579570689 - }], - "sent": "2016-06-01T15:52:37.341Z" - } -``` - - -#### GET /rules/:rule_id[](#get-rules-rule-id- "Permalink to this headline") - -Retrieve an existing rule on the stream by rule ID. Note that all rules are assigned a unique ID by X at the time of creation, rules that are deleted and recreated will receive a different unique rule ID. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **URL** | Found on the [Console - Products API Help tab](/x-api/enterprise-gnip-2.0/fundamentals/overview#products-tab), and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label/rules/:rule_id.json` | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | - - - -**Example cURL Request** - -The following example request demonstrates how to retrieve a rule by rule_id using cURL on the command line. - - curl -v -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label/rules/:rule_id.json" - - - - curl -v -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/companyname/publishers/twitter/prod/rules/735163830813134848.json" - -#### Response - -The following responses may be returned by the API for these requests. Non-200 responses should be retried, utilizing an exponential backoff for subsequent requests. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful, and the current rule is returned in JSON format. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/) contact support. | - - - -**Example Response** -``` - HTTP/1.1 200 OK - { - "rules": [{ - "value": "from:xdevelopers", - "tag": "tweetsfromxdevelopers", - "id": 735163830813134848 - "id_str":"735163830813134848" - }], - "sent": "2016-06-01T15:52:37.341Z" - } -``` - - -#### POST /rules _method=get[](#post-rules--method-get- "Permalink to this headline") - -Retrieves requested existing rules by list of rule IDs currently on a stream. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | Found on the API Help page, and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json?_method=get` | -| **Character Encoding** | UTF-8 | -| **Request Body Format** | JSON | -| **Request Body Size Limit** | 5 MB | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | -| **Compression** | Gzip compression is supported, but not required for these requests. | - - - -**Example curl Request** - -The following example request demonstrates how to add rules using cURL on the command line. -``` - curl -v -X POST -uexample@customer.com \ - "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json?_method=get" \ - -d '{"rule_ids":[734938587381145604,734938587381174273]}" -``` - - -#### Response - -The following responses may be returned by the API for these requests. Non-200 responses should be retried, utilizing an exponential backoff for subsequent requests. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful, and the current ruleset is returned in JSON format. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/) contact support. | - - - -**Example Response** -``` - HTTP/1.1 200 OK - { - "rules": [{ - "value": "from:furiouscamper", - "tag": null, - "id": 734938587381145604 - }, { - "value": "fish 🐟", - "tag": null, - "id": 734938587381174273 - }], - "sent": "2016-06-01T15:52:37.341Z" - } - - - - { - "error": { - "message": "Invalid JSON. The body must be in the format {\"rules\":[{\"value\":\"rule1\", \"tag\":\"tag1\"}, {\"value\":\"rule2\"}]} or {\"rule_ids\": [rule_id1, rule_id2, rule_id3, rule_id4, rule_id5]}", - "sent": "2013-08-16T00:50:00+00:00" - } - } - -``` - -#### POST /rules _method=delete[](#post-rules--method-delete- "Permalink to this headline") - -Deletes requested existing rules by list of rule values or rule IDs currently on a stream. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **Authentication** | Basic Authentication. Your login credentials must be included in the header of the request. | -| **Content Type** | "application/json". The request should specify this as the "Content-type". | -| **URL** | Found on the API Help page, and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json?_method=delete` | -| **Character Encoding** | UTF-8 | -| **Request Body Format** | JSON | -| **Request Body Size Limit** | 5 MB | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | - - - -#### Request Body Content - -Your request should provide rule data in the following formats: -``` - Content-type: "application/json" - { - "rules": - [ - {"value":"rule1"}, - {"value":"rule2"} - ] - } -``` -``` - Content-type: "application/json" - { - "rule_ids": - [ - 734938587381145604, - 734938587381174273 - ] - } -``` -**Example curl Request** - -The following example request demonstrates how to add rules using cURL on the command line. -``` - curl -v -X POST -uexample@customer.com \ - "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json?_method=delete" \ - -d '{"rules":[{"value":"testrule"}]}" -``` -``` - curl -v -X POST -uexample@customer.com \ - "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json?_method=delete" \ - -d '{"rule_ids":[734938587381145604,734938587381174273]}" -``` - - -#### Responses - -The following responses may be returned by the API for these requests. Non-200 responses should be retried following any necessary modifications to the rules being deleted. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | Indicates that the rule data supplied with the request consisted of valid JSON. However, note that if no rules are found in the ruleset for the PowerTrack stream based on a case-sensitive search, no rules will be deleted. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support. | - - - -**Example Responses** -``` - HTTP/1.1 200 OK - { - "summary": { - "deleted": 3, - "not_deleted": 0 - }, - "detail": [], - "sent": "2016-06-01T15:46:48.654Z" - } -``` - -``` - HTTP/1.1 200 OK - { - "summary": { - "deleted": 0, - "not_deleted": 3 - }, - "detail": [{ - "rule": { - "value": "Pizza", - "tag": null - }, - "deleted": false, - "message": "Rule does not exist" - }, { - "rule": { - "value": "eggplant", - "tag": null - }, - "deleted": false, - "message": "Rule does not exist" - }, { - "rule": { - "value": "fish", - "tag": null - }, - "deleted": false, - "message": "Rule does not exist" - }], - "sent": "2016-06-01T15:49:15.951Z" - } -``` -``` - HTTP/1.1 400 Bad Request - { - "error": { - "message": "Invalid JSON. The body must be in the format {\"rules\":[{\"value\":\"rule1\", \"tag\":\"tag1\"}, {\"value\":\"rule2\"}]} or {\"rule_ids\": [rule_id1, rule_id2, rule_id3, rule_id4, rule_id5]}", - "sent": "2013-08-16T00:50:00+00:00" - } - } -``` -**Important note on rule management:** Rule sets are indexed by the value or ruleID, not the tag; therefore, all rule additions must reference the rule value or ruleID. In order to to make a tag update to an existing rule, you must first delete it and then add it back with the new tag value. - -Rules must be unique per stream based on rule value, see below for a rule management example scenario: - -**CREATE RULE** - -Action: POST rule \{"value":"#XData","tag":"tagtextA"} \{"summary":\{"created":1,"not\_created":0},"detail":\[\{"rule":\{"value":"#XData","tag":"tagtextA","id":961664522481119232,"id\_str":"961664522481119232"},"created":true}\],"sent":"2018-02-08T18:14:23.691Z"} System: \{"value":"#XData","tag":"tagtextA","id":961664522481119232,"id_str":"961664522481119232"} - -**FAILED ATTEMPT TO UPDATE TAG** - -Action: POST rule \{"value":"#XData","tag":"tagtextB"} **Rule tags cannot be "updated" - This request is ignored because rule value `#XData` already exists. \{"summary":\{"created":0,"not\_created":1},"detail":\[\{"rule":\{"value":"#XData","tag":"tagtextB","id":961664522481119232,"id\_str":"961664522481119232"},"created":false,"message":"A rule with this value already exists"} System: \{"value":"#XData","tag":"tagtextA","id":961664522481119232,"id_str":"961664522481119232"} - -**FAILED ATTEMPT TO DELETE BY TAG** - -Action: POST method=delete rule \{"tag":"tagtextA"} **Rules cannot be deleted by tag. \{"summary":\{"deleted":0,"not\_deleted":1},"detail":\[\{"rule":\{"value":"","tag":null},"deleted":false,"message":"Rule does not exist"}\],"sent":"2018-02-08T18:42:37.004Z"} System: \{"value":"#XData","tag":"tagtextA","id":961664522481119232,"id\_str":"961664522481119232"} - -**DELETE BY ID** - -Action: POST method=delete rule \{"rule\_ids":\[961664522481119232\]} \{"summary":\{"deleted":1,"not\_deleted":0},"detail":\[\],"sent":"2018-02-08T18:53:54.185Z"} - -**DELETE BY VALUE** - -Action: POST method=delete rule \{"value":"#XData"} \{"summary":\{"deleted":1,"not_deleted":0},"detail":\[\],"sent":"2018-02-08T18:53:54.185Z"} - -**RECREATE RULE- NOW WITH NEW ID** - -Action: POST rule \{"value":"#XData","tag":"tagtextB"} \{"summary":\{"created":1,"not\_created":0},"detail":\[\{"rule":\{"value":"#XData","tag":"tagtextB","id":961675641140609025,"id\_str":"961675641140609025"},"created":true}\],"sent":"2018-02-08T18:58:34.586Z"} System: \{"value":"#XData","tag":"tagtextB","id":961675641140609025,"id_str":"961675641140609025"} - -#### POST /validation[](#post-validation- "Permalink to this headline") - -Validates PowerTrack rules. - -**Note:** Using this endpoint will not impact your PowerTrack streams. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | Found on the API Help page in console, and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label/validation.json` | -| **Character Encoding** | UTF-8 | -| **Request Body Format** | JSON | -| **Request Body Size Limit** | 5 MB | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | - - - -**Example curl Request** - -The following example request demonstrates how to add rules using cURL on the command line. -``` - curl --compressed -v -uexample@customer.com \ - "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label/validation.json" \ - -d '{ - "rules": [{ - "value": "Pizza OR 🍕 OR \"🍕\" sample:100" - }, { - "value": "from:contains:heart" - }, { - "value": "fish AND bird" - }, { - "value": "(((\"#quotedhashtag\"" - }, { - "value": "bounding_box:[-71.199636,42.230046,-70.979909,42.398619]" - }, { - "value": "from:jack" - }] - }' -``` -#### Response - -The following responses may be returned by the API for these requests. Non-200 responses should be retried, utilizing an exponential backoff for subsequent requests. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful, and the rule validation result is returned. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support. | - - - -**Example Response** - -This response indicates that one rule is valid and five are not valid. For rules that are not valid, there is a 'message' field explaining why the rule is not valid. -``` - HTTP/1.1 200 OK - { - "summary": { - "valid": 1, - "not_valid": 5 - }, - "detail": [{ - "rule": { - "value": "from:jack", - "tag": null - }, - "valid": true - }, { - "rule": { - "value": "Pizza OR 🍕 OR \"🍕\" sample:100", - "tag": null - }, - "valid": false, - "message": "The sample operator cannot be used with an OR. To use the sample operator with an OR in the rule, the ORed clauses must be grouped together with parenthesis. For example, to get 10% of activites that have term1 or term2, the rule should be (excluding the single quotes) '(term1 OR term2) sample:10' (at position 21)\n" - }, { - "rule": { - "value": "from:contains:heart", - "tag": null - }, - "valid": false, - "message": "Cannot parse rule at ':' (position 14)\n" - }, { - "rule": { - "value": "fish AND bird", - "tag": null - }, - "valid": false, - "message": "Ambiguous use of and as a keyword. Use a space to logically join two clauses, or \"and\" to find occurrences of and in text (at position 6)\n" - }, { - "rule": { - "value": "(((\"#quotedhashtag\"", - "tag": null - }, - "valid": false, - "message": "mismatched input 'EOF' expecting ')' (at position 20)\n\n" - }, { - "rule": { - "value": "bounding_box:[-71.199636,42.230046,-70.979909,42.398619]", - "tag": null - }, - "valid": false, - "message": "Cannot parse rule at '71.199636,42.230046,-70.979909,42.398619' (position 16)\n" - }], - "sent": "2017-03-16T02:33:01.827Z" - } -``` diff --git a/enterprise-api/fundamentals/consistency.mdx b/enterprise-api/fundamentals/consistency.mdx deleted file mode 100644 index 15c2fe0be..000000000 --- a/enterprise-api/fundamentals/consistency.mdx +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: API Consistency -sidebarTitle: Consistency -description: Consistent patterns across X API v2 endpoints -keywords: ["consistency", "API consistency", "uniform API", "consistent endpoints", "API design"] ---- - -X API v2 is designed with consistent patterns across all endpoints. Once you learn how one endpoint works, the same patterns apply everywhere. - ---- - -## Consistent patterns - -### URL structure - -All v2 endpoints follow a predictable pattern: - -``` -/version/resource/{id}?parameters -/version/resource/verb?parameters -``` - -Examples: - -``` -/2/tweets/1234567890 # Get a specific post -/2/tweets/search/recent # Search recent posts -/2/users/by/username/xdevelopers # Get user by username -/2/users/1234/followers # Get user's followers -``` - -### Response structure - -All responses use the same top-level structure: - -```json -{ - "data": { ... }, // Primary object(s) - "includes": { ... }, // Expanded objects - "meta": { ... }, // Pagination, counts - "errors": [ ... ] // Partial errors (if any) -} -``` - -### ID format - -All IDs are returned as strings to ensure language compatibility: - -```json -{ - "id": "1234567890123456789", - "author_id": "2244994945" -} -``` - ---- - -## Fields and expansions - -The same [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters work consistently: - -| Object | Fields parameter | Works across | -|:-------|:-----------------|:-------------| -| Post | `tweet.fields` | All endpoints returning posts | -| User | `user.fields` | All endpoints returning users | -| Media | `media.fields` | All endpoints with media expansions | -| Poll | `poll.fields` | All endpoints with poll expansions | -| Place | `place.fields` | All endpoints with place expansions | - ---- - -## Object schemas - -The same object type has the same fields regardless of which endpoint returns it: - -- A Post from search has the same fields as a Post from lookup -- A User from followers has the same fields as a User from search -- Expanded objects match their standalone counterparts - ---- - -## Authentication - -All endpoints use the same authentication methods: - -| Method | Header format | -|:-------|:--------------| -| Bearer Token | `Authorization: Bearer {token}` | -| OAuth 1.0a | `Authorization: OAuth {parameters}` | -| OAuth 2.0 | `Authorization: Bearer {user_token}` | - ---- - -## Error handling - -Errors follow a consistent format: - -```json -{ - "title": "Invalid Request", - "detail": "The query parameter is missing", - "type": "https://api.x.com/2/problems/invalid-request" -} -``` - -[See all error types →](/x-api/fundamentals/response-codes-and-errors) - ---- - -## Pagination - -All paginated endpoints use the same token system: - -| Parameter | Description | -|:----------|:------------| -| `max_results` | Results per page | -| `pagination_token` | Token from `next_token` or `previous_token` | - -[Learn more about pagination →](/x-api/fundamentals/pagination) - ---- - -## Naming conventions - -- American English spelling (`favorites` not `favourites`) -- Snake_case for field names (`author_id`, `created_at`) -- Consistent terminology (`retweet_count`, not `repost_count` in fields) - ---- - -## Empty values - -Fields with no value are omitted rather than returned as `null`: - -```json -// User without a bio -{ - "id": "1234", - "name": "Example User", - "username": "example" - // "description" is omitted, not null -} -``` - ---- - -## Entity consistency - -The `entities` object only contains entities parsed from text: - -- `urls` -- `hashtags` -- `mentions` -- `cashtags` - -Media and polls are in `attachments`, not `entities`. - ---- - -## What this means for you - - - - Patterns you learn on one endpoint apply to all endpoints. - - - Same object types have same structures across the API. - - - Build reusable functions for common patterns. - - - Consistent error formats simplify troubleshooting. - - - ---- - -## Report inconsistencies - -Found an inconsistency? Let us know: - -- [Developer Forum](https://devcommunity.x.com) -- [Developer Feedback](https://t.co/devfeedback) diff --git a/enterprise-api/fundamentals/consuming-streaming-data.mdx b/enterprise-api/fundamentals/consuming-streaming-data.mdx deleted file mode 100644 index 9648fa71d..000000000 --- a/enterprise-api/fundamentals/consuming-streaming-data.mdx +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: Consuming streaming data -sidebarTitle: Consuming streaming data -description: Best practices for building clients that consume X streaming APIs -keywords: ["consuming streaming data", "streaming data", "process stream", "handle stream", "stream processing", "stream consumption", "streaming API"] ---- - -Learn how to build robust clients that consume data from X streaming endpoints. - -## Streaming endpoints overview - -X streaming endpoints are categorized by volume: - -| Category | Endpoints | Description | -|:---------|:----------|:------------| -| **High-volume streams** | **Firehose**, [Volume Streams](/x-api/posts/volume-streams/introduction) (1% and 10% sampled) | Deliver large volumes of Post data without filtering. Designed for comprehensive coverage of platform activity. | -| **Lower-volume streams** | [Filtered Stream](/x-api/posts/filtered-stream/introduction) | Allow you to specify keywords or criteria to receive only matching Posts. Ideal for targeted monitoring. | -| **Low-latency streams** | [Powerstream](/x-api/powerstream/introduction) | Optimized for speed with minimal delay. Best for use cases requiring real-time data delivery. | - -## Data delivery and latency - -X API streaming endpoints prioritize **data hydration and delivery**. To ensure you receive hydrated Post data with all metadata, these streams have a **P99 latency of approximately 6-7 seconds**. - -### Delivery guarantees - -| Metric | Value | -|:-------|:------| -| Retry strategy | Exponential back-off | -| P99 latency | ~6-7 seconds | - -### High-volume streams - -For high-volume streams like Firehose and Sample (1% and 10%) streams, **99% of all Posts are delivered within 1 minute** of their creation time. This guarantee is based on the high-volume, continuous nature of the full data feed. - -### Lower-volume streams - -For streams with potentially lower-volume like Filtered Stream, delivery times may vary based on the specificity of your filters and the resulting volume of matching Posts. - - -If your use case requires lower latency, consider [Powerstream](/x-api/powerstream/introduction), which is optimized for speed and delivers data with minimal delay. - - - -Latency and data delivery may be negatively impacted during outages. Refer to the [status page](https://docs.x.com/status) for updates when issues occur. - - ---- - -## Client design - -When building a solution with streaming endpoints, your client needs to: - -1. **Establish an HTTPS streaming connection** to the streaming endpoint -2. **Handle low data volumes** — Maintain the connection, detecting Post objects and keep-alive signals -3. **Handle high data volumes** — Decouple stream ingestion from processing using asynchronous processes, and ensure client-side buffers are flushed regularly -4. **Manage volume tracking** on the client side -5. **Detect disconnections** and reconnect automatically - -For endpoints with rules (like Filtered Stream and Powerstream), your client should also asynchronously send requests to manage rules without disconnecting from the stream. - ---- - -## Connecting to a streaming endpoint - -Establishing a connection to X API streaming endpoints means making a very long-lived HTTP request and parsing the response incrementally. Conceptually, you can think of it as downloading an infinitely long file over HTTP. - -Once a connection is established, the X server will deliver Post events through the connection as long as it remains open. - -```python -import requests - -def connect_to_stream(url, bearer_token): - headers = {"Authorization": f"Bearer {bearer_token}"} - - response = requests.get(url, headers=headers, stream=True) - - for line in response.iter_lines(): - if line: - # Process the Post - print(line.decode("utf-8")) -``` - ---- - -## Consuming data - -JSON objects from the stream may have fields in any order, and not all fields will be present in all circumstances. Posts are not delivered in sorted order, and duplicate messages may occur. Over time, new message types may be added to the stream. - -Your client must tolerate: - -- Fields appearing in any order -- Unexpected or missing fields -- Non-sorted Posts -- Duplicate messages -- New message types appearing at any time - ---- - -## Buffering - -Streaming endpoints send data as quickly as it becomes available, which can result in high volumes. If the X server cannot write new data to the stream (for example, if your client is not reading fast enough), it will buffer content on its end. However, when this buffer is full, the connection will be dropped and buffered Posts will be lost. - -One way to identify when your app is falling behind is to compare the timestamp of received Posts with the current time and track this over time. - -To minimize stream backups: - -- **Read the stream quickly** — Don't do processing work as you read. Hand activities to another thread/process/data store for asynchronous processing -- **Ensure sufficient bandwidth** — Your data center needs inbound bandwidth for large sustained volumes as well as spikes (5-10x normal volume) - ---- - -## Responding to system messages - -### Keep-alive signals - -At least every 20 seconds, the stream sends a keep-alive signal (heartbeat) in the form of a `\r\n` carriage return through the open connection. This prevents your client from timing out. Your client should be tolerant of these characters. - -If your client implements a read timeout on your HTTP library, it can rely on the HTTP protocol to throw an event if no data is read within this period. It's recommended to wrap HTTP methods with error/event handlers to detect these timeouts and trigger a reconnect. - -### Error messages - -Streaming endpoints may deliver in-stream error messages. Your client should be tolerant of changing message payloads. - -Example error message format: - -```json -{ - "errors": [{ - "title": "operational-disconnect", - "disconnect_type": "UpstreamOperationalDisconnect", - "detail": "This stream has been disconnected upstream for operational reasons.", - "type": "https://api.x.com/2/problems/operational-disconnect" - }] -} -``` - - -Error messages indicating a force disconnect due to a full buffer may never reach your client if the backup prevents delivery. Your app should not depend solely on these messages to initiate reconnection. - - ---- - -## Usage tracking - -Monitor your stream data volumes for unexpected deviations. A significant decrease in volume may indicate an issue other than disconnection — the stream would still receive keep-alive signals and some data, but reduced Post volume should prompt investigation. - -To create monitoring: - -1. Track the number of Posts expected in a set time period -2. If volume falls below a threshold and doesn't recover, initiate alerts -3. Also monitor for large increases, especially when modifying rules or during events that spike Post activity - - -Posts delivered through streaming endpoints count towards your monthly Post volume. Track and adjust consumption to optimize usage. If volume is high, consider adding a `sample:` operator to rules to reduce matching from 100% to `sample:50` or `sample:25`. - - ---- - -## Multi-threaded processing - -Building a multi-threaded application is key for handling high-volume streams. A best practice: - -1. **Stream thread** — A lightweight thread that establishes the connection and writes received JSON to a memory structure or buffered stream reader -2. **Processing thread(s)** — Separate threads that consume from the buffer and do the heavy lifting: parsing JSON, preparing database writes, or other application logic - -This design allows your service to scale efficiently as incoming Post volumes change. - -```mermaid actions={false} -flowchart LR - A["Stream Connection
(lightweight)"] --> B["Memory Buffer
(FIFO)"] --> C["Processing Thread(s)
(heavy work)"] -``` - ---- - -## Next steps - - - - Reconnect gracefully when connections drop - - - Handle high throughput streams - - - Build resilient streaming applications - - diff --git a/enterprise-api/fundamentals/conversation-id.mdx b/enterprise-api/fundamentals/conversation-id.mdx deleted file mode 100644 index 5694bf899..000000000 --- a/enterprise-api/fundamentals/conversation-id.mdx +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Conversation ID -sidebarTitle: Conversation ID -description: Track and reconstruct conversation threads -keywords: ["conversation ID", "conversation threads", "reply threads", "thread tracking", "conversation tracking"] ---- - -Every reply on X belongs to a conversation thread. The `conversation_id` field lets you identify, track, and reconstruct entire conversation trees. - ---- - -## How it works - -When someone posts and others reply, all replies share the same `conversation_id`—the ID of the original post that started the conversation. - -```mermaid actions={false} -flowchart TD - A["Original post (ID: 1234567890)
← conversation_id for all replies"] --> B["Reply 1 (ID: 1234567891)
conversation_id: 1234567890"] - A --> C["Reply 2 (ID: 1234567892)
conversation_id: 1234567890"] - B --> D["Reply to Reply 1
conversation_id: 1234567890"] - C --> E["Reply to Reply 2
conversation_id: 1234567890"] -``` - -No matter how deep the thread goes, all posts share the same `conversation_id`. - ---- - -## Requesting conversation_id - -Add `conversation_id` to your `tweet.fields`: - -```bash -curl "https://api.x.com/2/tweets/1234567891?tweet.fields=conversation_id,in_reply_to_user_id,referenced_tweets" \ - -H "Authorization: Bearer $TOKEN" -``` - -Response: - -```json -{ - "data": { - "id": "1234567891", - "text": "@user Great point!", - "conversation_id": "1234567890", - "in_reply_to_user_id": "2244994945", - "referenced_tweets": [{ - "type": "replied_to", - "id": "1234567890" - }] - } -} -``` - ---- - -## Getting a full conversation - -Use `conversation_id` as a search operator to retrieve all posts in a thread: - -```bash -curl "https://api.x.com/2/tweets/search/recent?\ -query=conversation_id:1234567890&\ -tweet.fields=author_id,created_at,in_reply_to_user_id&\ -expansions=author_id" \ - -H "Authorization: Bearer $TOKEN" -``` - -This returns all replies to the original post, sorted reverse-chronologically. - ---- - -## Use cases - - - -Build the full conversation tree: - -```python -import requests - -conversation_id = "1234567890" -url = f"https://api.x.com/2/tweets/search/recent" -params = { - "query": f"conversation_id:{conversation_id}", - "tweet.fields": "author_id,in_reply_to_user_id,referenced_tweets,created_at", - "max_results": 100 -} - -response = requests.get(url, headers=headers, params=params) -replies = response.json()["data"] - -# Sort by created_at to get chronological order -replies.sort(key=lambda x: x["created_at"]) -``` - - -Stream replies to specific conversations in real-time: - -```bash -# Add a filtered stream rule for a conversation -curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \ - -H "Authorization: Bearer $TOKEN" \ - -d '{"add": [{"value": "conversation_id:1234567890"}]}' -``` - - -Count replies in a conversation: - -```bash -curl "https://api.x.com/2/tweets/counts/recent?\ -query=conversation_id:1234567890" \ - -H "Authorization: Bearer $TOKEN" -``` - - - ---- - -## Related fields - -| Field | Description | -|:------|:------------| -| `conversation_id` | ID of the original post that started the thread | -| `in_reply_to_user_id` | User ID of the post being replied to | -| `referenced_tweets` | Array with `type: "replied_to"` and the parent post ID | - ---- - -## Example: Full thread retrieval - -```json -{ - "data": [ - { - "id": "1234567893", - "text": "@user2 @user1 I agree with you both!", - "conversation_id": "1234567890", - "author_id": "3333333333", - "created_at": "2024-01-15T12:05:00.000Z", - "in_reply_to_user_id": "2222222222", - "referenced_tweets": [{"type": "replied_to", "id": "1234567892"}] - }, - { - "id": "1234567892", - "text": "@user1 That's interesting!", - "conversation_id": "1234567890", - "author_id": "2222222222", - "created_at": "2024-01-15T12:03:00.000Z", - "in_reply_to_user_id": "1111111111", - "referenced_tweets": [{"type": "replied_to", "id": "1234567890"}] - }, - { - "id": "1234567891", - "text": "@user1 Great point!", - "conversation_id": "1234567890", - "author_id": "4444444444", - "created_at": "2024-01-15T12:02:00.000Z", - "in_reply_to_user_id": "1111111111", - "referenced_tweets": [{"type": "replied_to", "id": "1234567890"}] - } - ], - "meta": { - "result_count": 3 - } -} -``` - ---- - -## Notes - -- The original post's `conversation_id` equals its own `id` -- `conversation_id` is available on all v2 endpoints that return posts -- Use with [filtered stream](/x-api/posts/filtered-stream/introduction) to monitor conversations in real-time -- Combine with [pagination](/x-api/fundamentals/pagination) for large threads - ---- - -## Next steps - - - - Search by conversation_id. - - - Monitor conversations in real-time. - - diff --git a/enterprise-api/fundamentals/data-dictionary.mdx b/enterprise-api/fundamentals/data-dictionary.mdx deleted file mode 100644 index 98c55aea9..000000000 --- a/enterprise-api/fundamentals/data-dictionary.mdx +++ /dev/null @@ -1,2739 +0,0 @@ ---- -title: Data Dictionary -sidebarTitle: Data Dictionary -description: Complete field reference for X API v2 objects -keywords: ["data dictionary", "object model", "tweet object", "user object", "API objects", "data structure", "JSON schema", "API response", "tweet fields", "user fields"] ---- - -The X API returns structured JSON objects representing posts, users, media, and more. This reference documents every field available for each object type. - ---- - -## Quick navigation - -| Object | Description | Fields parameter | -|:-------|:------------|:-----------------| -| [Post (Tweet)](#post-tweet) | Posts, replies, reposts, quotes | `tweet.fields` | -| [User](#user) | Account profiles and metadata | `user.fields` | -| [Space](#space) | Live audio conversations | `space.fields` | -| [List](#list) | Curated collections of accounts | `list.fields` | -| [Media](#media) | Images, videos, GIFs | `media.fields` | -| [Poll](#poll) | Poll questions and options | `poll.fields` | -| [Place](#place) | Location and geo data | `place.fields` | - - -Use [fields parameters](/x-api/fundamentals/fields) to request specific fields, and [expansions](/x-api/fundamentals/expansions) to include related objects. - - ---- - -## Post (Tweet) - -Posts are the core content unit on X. Each Post object includes text, metadata, and references to related objects like authors, media, and polls. - -**Default fields:** `id`, `text`, `edit_history_tweet_ids` - -Use `tweet.fields` to request additional fields and `expansions` to include related objects. - -### All Post fields - -| Field Value | Type | Description | How it Can Be Used | -|:-----------------------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------| -| **id (default)** | string | The unique identifier of the requested Tweet. | Use this to programmatically retrieve a specific Tweet. | -| **text (default)** | string | The actual UTF-8 text of the Tweet. See [twitter-text](https://github.com/twitter/twitter-text/) for details on valid characters. | Keyword extraction and sentiment analysis/classification. | -| **edit_history_tweet_ids (default)** | object | Unique identifiers indicating all versions of a Tweet. For Tweets with no edits, there will be one ID. For Tweets with an edit history, there will be multiple IDs. | Use this information to find the edit history of a Tweet. | -| **article** | object | Contains metadata for the Article present in this Tweet. | Use this to get the text and entities of an Article. | -| **attachments** | object | Specifies the type of attachments (if any) present in this Tweet. | Understanding the objects returned for requested expansions. | -| **author_id** | string | The unique identifier of the User who posted this Tweet. | Hydrating User object, sharing dataset for peer review. | -| **card_uri** | string | The URI for the Card present in this tweet. | | -| **community_id** | string | The unique identifier for the Community this Post belongs to. | | -| **context_annotations** | array | Contains context annotations for the Tweet. | Entity recognition/extraction, topical analysis. | -| **conversation_id** | string | The Tweet ID of the original Tweet of the conversation (which includes direct replies, replies of replies). | Use this to reconstruct the conversation from a Tweet. | -| **created_at** | date (ISO 8601) | Creation time of the Tweet. | Useful for time-series analysis and understanding when a Tweet was created. | -| **display_text_range** | array | An array containing a start and end index for the portion of text that gets displayed. | Useful for knowing which portion of text is displayed by default for long posts. | -| **edit_controls** | object | Indicates how much longer the Tweet can be edited and the number of remaining edits. | Use this to determine if a Tweet is eligible for editing. | -| **entities** | object | Entities that have been parsed out of the text of the Tweet. See entities in Twitter Objects. | Provides additional information about hashtags, URLs, mentions, etc. | -| **geo** | object | Indicates the location or place of a geo-tagged Tweet. | Use this to determine get location of a geo-tagged Tweet. | -| **in_reply_to_user_id** | string | If the represented Tweet is a reply, this field will contain the original Tweet’s author ID. | Determine if a Tweet was in reply to another Tweet. | -| **lang** | string | Language of the Tweet, if detected by Twitter. | Classify Tweets by spoken language. | -| **non_public_metrics** | object | Non-public engagement metrics for the Tweet at the time of the request. Requires user context authentication. Includes `impression_count`, `user_profile_clicks`, `url_link_clicks`, and `engagements`. | Determine total impressions and engagement generated for the Tweet. | -| **note_tweet** | object | Contains the full text of a Post for long-form Posts (>280 characters). | Get the complete text of a post. | -| **organic_metrics** | object | Engagement metrics, tracked in an organic context, for the Tweet at the time of the request. Requires user context authentication. | Measure organic engagement for the Tweet. | -| **possibly_sensitive** | boolean | Indicates if the content may be recognized as sensitive. | Study circulation of certain types of content. | -| **promoted_metrics** | object | Engagement metrics, tracked in a promoted context, for the Tweet at the time of the request. Requires user context authentication. | Measure engagement for the Tweet when it was promoted. | -| **public_metrics** | object | Public engagement metrics for the Tweet at the time of the request. Includes `retweet_count`, `reply_count`, `like_count`, `quote_count`, `impression_count`, and `bookmark_count`. | Measure Tweet engagement. | -| **referenced_tweets** | array | A list of Tweets this Tweet refers to, such as Retweets, quoted Tweets, or replies. | Understand conversational aspects of retweets, etc. | -| **reply_settings** | string | Shows who can reply to a given Tweet. Options are "everyone", "mentioned_users", and "followers". | Determine conversation reply settings for the Tweet. | -| **withheld** | object | Contains withholding details for [withheld content](https://help.x.com/en/rules-and-policies/tweet-withheld-by-country). | | -| **scopes** | object | Contains scope details for the tweet. | Indicates who can view the post. Only returned for promoted posts. | -| **media_metadata** | array | Contains metadata for media attachments of the Tweet. | Get additional metadata like the `alt_text` of a Tweet's media attachment. | - -**Retrieving a Tweet Object** - -**Sample Request** - -In the following request, we are requesting fields for the Tweet on the [Tweets lookup](/resources/fundamentals/rate-limits) endpoint. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication). - -```bash -curl --request GET 'https://api.x.com/2/tweets?ids=1212092628029698048&tweet.fields=attachments,author_id,context_annotations,created_at,entities,geo,id,in_reply_to_user_id,lang,possibly_sensitive,public_metrics,referenced_tweets,text,withheld&expansions=referenced_tweets.id' --header 'Authorization: Bearer $BEARER_TOKEN' -``` - -**Sample Response** - -``` -{ - "data": [ - { - "text": "We believe the best future version of our API will come from building it with YOU. Here’s to another great year with everyone who builds on the Twitter platform. We can’t wait to continue working with you in the new year. https://t.co/yvxdK6aOo2", - "edit_history_tweet_ids": [ - "1212092628029698048" - ], - "lang": "en", - "in_reply_to_user_id": "2244994945", - "entities": { - "urls": [ - { - "start": 222, - "end": 245, - "url": "https://t.co/yvxdK6aOo2", - "expanded_url": "https://x.com/LovesNandos/status/1211797914437259264/photo/1", - "display_url": "pic.x.com/yvxdK6aOo2", - "media_key": "16_1211797899316740096" - } - ], - "annotations": [ - { - "start": 42, - "end": 44, - "probability": 0.5359, - "type": "Other", - "normalized_text": "API" - }, - { - "start": 144, - "end": 150, - "probability": 0.9832, - "type": "Other", - "normalized_text": "Twitter" - } - ] - }, - "author_id": "2244994945", - "referenced_tweets": [ - { - "type": "replied_to", - "id": "1212092627178287104" - } - ], - "id": "1212092628029698048", - "public_metrics": { - "retweet_count": 7, - "reply_count": 3, - "like_count": 38, - "quote_count": 1, - "bookmark_count": 2, - "impression_count": 1250 - }, - "context_annotations": [ - { - "domain": { - "id": "29", - "name": "Events [Entity Service]", - "description": "Real world events. " - }, - "entity": { - "id": "1186637514896920576", - "name": " New Years Eve" - } - }, - { - "domain": { - "id": "29", - "name": "Events [Entity Service]", - "description": "Real world events. " - }, - "entity": { - "id": "1206982436287963136", - "name": "Happy New Year: It’s finally 2020 everywhere!", - "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages " - } - }, - { - "domain": { - "id": "119", - "name": "Holiday", - "description": "Holidays like Christmas or Halloween" - }, - "entity": { - "id": "1186637514896920576", - "name": " New Years Eve" - } - }, - { - "domain": { - "id": "119", - "name": "Holiday", - "description": "Holidays like Christmas or Halloween" - }, - "entity": { - "id": "1206982436287963136", - "name": "Happy New Year: It’s finally 2020 everywhere!", - "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages " - } - }, - { - "domain": { - "id": "30", - "name": "Entities [Entity Service]", - "description": "Entity Service top level domain, every item that is in Entity Service should be in this domain" - }, - "entity": { - "id": "781974596752842752", - "name": "Services" - } - }, - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - }, - { - "domain": { - "id": "131", - "name": "Unified Twitter Taxonomy", - "description": "A taxonomy of user interests. " - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - }, - { - "domain": { - "id": "131", - "name": "Unified Twitter Taxonomy", - "description": "A taxonomy of user interests. " - }, - "entity": { - "id": "847868745150119936", - "name": "Family & relationships", - "description": "Hobbies and interests" - } - }, - { - "domain": { - "id": "131", - "name": "Unified Twitter Taxonomy", - "description": "A taxonomy of user interests. " - }, - "entity": { - "id": "1196446161223028736", - "name": "Social media" - } - }, - { - "domain": { - "id": "29", - "name": "Events [Entity Service]", - "description": "Real world events. " - }, - "entity": { - "id": "1206982436287963136", - "name": "Happy New Year: It’s finally 2020 everywhere!", - "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages " - } - }, - { - "domain": { - "id": "119", - "name": "Holiday", - "description": "Holidays like Christmas or Halloween" - }, - "entity": { - "id": "1206982436287963136", - "name": "Happy New Year: It’s finally 2020 everywhere!", - "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages " - } - } - ], - "created_at": "2019-12-31T19:26:16.000Z", - "attachments": { - "media_keys": [ - "16_1211797899316740096" - ] - }, - "possibly_sensitive": false - } - ], - "includes": { - "tweets": [ - { - "text": "These launches would not be possible without the feedback you provided along the way, so THANK YOU to everyone who has contributed your time and ideas. Have more feedback? Let us know ⬇️ https://t.co/Vxp4UKnuJ9", - "edit_history_tweet_ids": [ - "1212092627178287104" - ], - "lang": "en", - "in_reply_to_user_id": "2244994945", - "entities": { - "urls": [ - { - "start": 187, - "end": 210, - "url": "https://t.co/Vxp4UKnuJ9", - "expanded_url": "https://twitterdevfeedback.uservoice.com/forums/921790-twitter-developer-labs", - "display_url": "twitterdevfeedback.uservoice.com/forums/921790-…", - "status": 200, - "title": "Updates on our feedback channels", - "description": "We build our developer platform in the open, with your input and feedback. Over the past year, hearing directly from you and the users of your apps has helped us build developer products that cater to the use case you helped us identify. We want to make this the way we build products, and moving forward, we are consolidating our feedback channels. Meeting you where you are Effective today, we are going to retire our UserVoice feedback channel in favor of more frequent direct engagements with y...", - "unwound_url": "https://devcommunity.x.com/t/updates-on-our-feedback-channels/169706" - } - ] - }, - "author_id": "2244994945", - "referenced_tweets": [ - { - "type": "replied_to", - "id": "1212092626247110657" - } - ], - "id": "1212092627178287104", - "public_metrics": { - "retweet_count": 2, - "reply_count": 1, - "like_count": 19, - "quote_count": 0, - "bookmark_count": 0, - "impression_count": 430 - }, - "created_at": "2019-12-31T19:26:16.000Z", - "possibly_sensitive": false - } - ] - } - ``` - -### User - -The user object contains Twitter user account metadata describing the referenced user. The user object is the primary object returned in the [users lookup](/x-api/users/lookup/introduction) endpoint. When requesting additional user fields on this endpoint, simply use the fields parameter `user.fields`. - -The user object can also be found as a child object and expanded in the Tweet object. The object is available for expansion with `?expansions=author_id` or `?expansions=in_reply_to_user_id` to get the condensed object with only default fields. Use the expansion with the field parameter: `user.fields` when requesting additional fields to complete the object. -  - -| Field value | Type | Description | How it can be used | -| :--- | :--- | :--- | :--- | -| id (default) | string | The unique identifier of this user.

`"id": "2244994945"` | Use this to programmatically retrieve information about a specific Twitter user. | -| name (default) | string | The name of the user, as they’ve defined it on their profile. Not necessarily a person’s name. Typically capped at 50 characters, but subject to change.

`"name": "Twitter Dev"` | | -| username (default) | string | The Twitter screen name, handle, or alias that this user identifies themselves with. Usernames are unique but subject to change. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names.

`"username": "TwitterDev"` | | -| affiliation | object | Contains details about a user's affiliation. | Can be used to get a user's affiliate badge. | -| confirmed_email | string | The confirmed email of the authenticated user. | | -| connection_status | array | Provides a list of relation between the authenticating user and the user being looked up such as following, followed, follow request sent, follow request received, blocking, muting

"connection_status": \[
           "follow\_request\_received",
           "follow\_request\_sent",
           "blocking",
           "followed_by",
           "following",
           "muting"
\] | Can be used to determine the connection status between the authenticating user and the user being looked up. | -| created_at | date (ISO 8601) | The UTC datetime that the user account was created on Twitter.

`"created_at": "2013-12-14T04:35:55.000Z"` | Can be used to determine how long a someone has been using Twitter | -| description | string | The text of this user's profile description (also known as bio), if the user provided one.

`"description": "The voice of the X Dev team and your official source for updates, news, and events, related to the X API."` | | -| entities | object | Contains details about text that has a special meaning in the user's description.

`"entities": {
       "url": {
           "urls": [
               {
                   "start": 0,
                   "end": 23,
                   "url": "https://t.co/3ZX3TNiZCY",
                   "expanded_url": "/content/developer-twitter/en/community",
                   "display_url": "developer.x.com/en/community"
               }
           ]
       },
       "description": {
           "urls": [
               {
                   "start": 0,
                   "end": 23,
                   "url": "https://t.co/3ZX3TNiZCY",
                   "expanded_url": "/content/developer-twitter/en/community",
                   "display_url": "developer.x.com/en/community"
               },
           "hashtags": [
               {
                   "start": 23,
                   "end": 30,
                   "tag": "DevRel"
               },
               {
                   "start": 113,
                   "end": 130,
                   "tag": "BlackLivesMatter"
               },
           "mentions": [
               {
                   "start": 0,
                   "end": 10,
                   "tag": "TwitterDev"
               },
           "cashtags": [
               {
                   "start": 12,
                   "end": 16,
                   "tag": "twtr"
               }
           ]
       }
   }` | Entities are JSON objects that provide additional information about hashtags, urls, user mentions, and cashtags associated with the description. Reference each respective entity for further details.

All user ******start****** indices are inclusive, while all user ******end****** indices are exclusive. | -| is_identity_verified | boolean | Indicates if the user is ID verified. | | -| location | string | The location specified in the user's profile, if the user provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries.

`"location": "127.0.0.1"` | | -| most_recent_tweet_id | string | Unique identifier of this user's most recent Tweet. | Determine the most recent Tweet of the user. | -| parody | boolean | Indicates whether or not this user account has the Parody label. | | -| pinned_tweet_id | string | Unique identifier of this user's pinned Tweet.

`"pinned_tweet_id": "1255542774432063488"` | Determine the Tweet pinned to the top of the user’s profile. Can potentially be used to determine the user’s language. | -| profile_banner_url | string | The URL to the profile banner for this user, as shown on the user's profile.

`"profile_banner_url": "https://pbs.twimg.com/profile_banners/1716450569358098432/1721022977"` | Can be used to download this user's profile banner. | -| profile_image_url | string | The URL to the profile image for this user, as shown on the user's profile.

`"profile_image_url": "https://pbs.twimg.com/profile_images/1267175364003901441/tBZNFAgA_normal.jpg"` | Can be used to download this user's profile image. | -| protected | boolean | Indicates if this user has chosen to protect their Tweets (in other words, if this user's Tweets are private).

`"protected": false` | | -| public_metrics | object | Contains details about activity for this user.

`"public_metrics": {             "followers_count": 507902,             "following_count": 1863,             "tweet_count": 3561,             "listed_count": 1550         }` | Can potentially be used to determine a Twitter user’s reach or influence, quantify the user’s range of interests, and the user’s level of engagement on Twitter. | -| receives_your_dm | boolean | Indicates whether or not this user will receive the authenticated user's DM. | | -| subscription | object | Contains details on whether or not the user is subscribed to the authenticated user. | | -| subscription_type | string | A string representing the type of X Premium subscription the authenticated user has. Example: `None`, `Basic`, `Premium`,`PremiumPlus`. Will always return `None` if the user is not the authenticated user. | | -| url | string | The URL specified in the user's profile, if present.

`"url": "https://t.co/3ZX3TNiZCY"` | A URL provided by a Twitter user in their profile. This could be a homepage, but is not always the case. | -| verified | boolean | Indicates if this user is a verified Twitter User.

`"verified": true` | Indicates whether or not this Twitter user has a verified account. A verified account lets people know that an account of public interest is authentic. | -| verified_followers_count | string | A string representing the number of verified followers of a user. | | -| verified_type | string | A string representing the type of verification a user has. Example: "blue", "business", "government" | | -| withheld | object | Contains withholding details for [withheld content](https://help.x.com/en/rules-and-policies/tweet-withheld-by-country), if applicable. | | - -**Retrieving a user object** - -**Sample Request** - -In the following request, we are requesting fields for the user on the [users lookup](/x-api/users/lookup/introduction) endpoint. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token). -  - -```{ - curl --request GET 'https://api.x.com/2/users? - ids=2244994945&user.fields=created_at,description,entities,id,location,name,pinned_tweet_id,profile_image_url,protected,url,username,verified,withheld&expansions=pinned_tweet_id' - --header 'Authorization: Bearer $BEARER_TOKEN' - } - ``` - - -**Sample Response** - - ```{ - "data": [ - { - "id": "2244994945", - "name": "Twitter Dev", - "username": "TwitterDev", - "location": "127.0.0.1", - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/3ZX3TNiZCY", - "expanded_url": "/content/developer-twitter/en/community", - "display_url": "developer.x.com/en/community" - } - ] - }, - "description": { - "hashtags": [ - { - "start": 23, - "end": 30, - "tag": "DevRel" - }, - { - "start": 113, - "end": 130, - "tag": "BlackLivesMatter" - } - ] - } - }, - "verified": true, - "description": "The voice of Twitter's #DevRel team, and your official source for updates, news, & events about Twitter's API. \n\n#BlackLivesMatter", - "url": "https://t.co/3ZX3TNiZCY", - "profile_image_url": "https://pbs.twimg.com/profile_images/1267175364003901441/tBZNFAgA_normal.jpg", - "protected": false, - "pinned_tweet_id": "1255542774432063488", - "created_at": "2013-12-14T04:35:55.000Z" - } - ], - "includes": { - "tweets": [ - { - "id": "1255542774432063488", - "text": "During these unprecedented times, what’s happening on Twitter can help the world better understand & respond to the pandemic. \n\nWe're launching a free COVID-19 stream endpoint so qualified devs & researchers can study the public conversation in real-time. https://t.co/BPqMcQzhId" - } - ] - } -} -``` - -### Space - -Spaces allow expression and interaction via live audio conversations. The Space data dictionary contains relevant metadata about a Space; all the details are updated in real time. - -User objects can be found and expanded in the user resource. These objects are available for expansion by adding at least one of `host_ids`, `creator_id`, `speaker_ids`, `mentioned_user_ids` to the `expansions` query parameter. - -Unlike Tweets, Spaces are ephemeral and become unavailable after they end or when they are canceled by their creator. When your app handles Spaces data, you are responsible for returning the most up-to-date information and must remove data that is no longer available from the platform. The [Spaces lookup endpoints](/x-api/spaces/lookup/introduction) can help you ensure you respect the users’ expectations and intent. - -| Field Value | Type | Description | How it can be used | -| :-------------------- | :--------------- | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- | -| id (default) | string | The unique identifier of the requested Space.
`"id": "1zqKVXPQhvZJB"` | Uniquely identify a Space returned in the response. | -| state (default) | string | Indicates if the Space has started, will start, or has ended.
`"state": "live"` | Filter live or scheduled Spaces. | -| created_at | date (ISO 8601) | Creation time of this Space.
`"created_at": "2021-07-04T23:12:08.000Z"` | Understand when a Space was created and sort by time. | -| creator_id | string | Unique identifier of the Space creator.
`"creator_id": "2244994945"` | | -| ended_at | date (ISO 8601) | Time when the Space ended, if applicable.
`"ended_at": "2021-07-04T00:11:44.000Z"` | Determine when a live Space ended for runtime duration. | -| host_ids | array | Unique identifiers of the Space hosts.
`"host_ids": ["2244994945", "6253282"]` | Expand User objects, understand engagement. | -| lang | string | Language of the Space, if detected.
`"lang": "en"` | Classify Spaces by language. | -| is_ticketed | boolean | Indicates if this is a ticketed Space.
`"is_ticketed": false` | Highlight content of interest. | -| invited_user_ids | array | List of user IDs invited as speakers.
`"invited_user_ids": ["2244994945", "6253282"]` | Expand User objects, understand engagement. | -| participant_count | integer | Number of users in the Space, including Hosts and Speakers.
`"participant_count": 420` | Understand engagement, create reports. | -| subscriber_count | integer | Number of people who set a reminder for a Space.
`"subscriber_count": 36` | Understand event interest. | -| scheduled_start | date (ISO 8601) | Scheduled start time of the Space.
`"scheduled_start": "2021-07-14T08:00:00.000Z"` | Integrate with calendar notifications. | -| speaker_ids | array | List of users who spoke at any point.
`"speaker_ids": ["2244994945", "6253282"]` | Expand User objects, understand engagement. | -| started_at | date (ISO 8601) | Actual start time of a Space.
`"started_at": "2021-07-14T08:00:12.000Z"` | Determine Space start time. | -| title | string | Title of the Space.
`"title": "Say hello to the Space data object!"` | Understand keywords, hashtags, mentions. | -| topic_ids | array | IDs of topics selected by the Space creator.
`"topic_ids": ["2244994945", "6253282"]` | Understand keywords, hashtags, mentions. | -| updated_at | date (ISO 8601) | Last update to Space metadata.
`"updated_at": "2021-07-11T14:44:44.000Z"` | Keep information up to date. | - -**Retrieving a Space Object ** - -**Sample Request** - -In the following request, we are requesting fields for the Space on the [Spaces lookup endpoint](/x-api/spaces/lookup/introduction). Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token). - -```bash -curl "https://api.x.com/2/spaces/1DXxyRYNejbKM?space.fields=created_at,creator_id,created_athost_ids,lang,is_ticketed,invited_user_ids,participant_count,scheduled_start,speaker_ids,started_at,state,title,updated_at&expansions=creator_id,host_ids,invited_user_ids,speaker_ids" --header "Authorization: Bearer $BEARER_TOKEN" -``` - -** Sample Response ** - -``` -{ - "data": { - "id": "1zqKVXPQhvZJB", - "state": "live", - "created_at": "2021-07-04T23:12:08.000Z", - "host_ids": [ - "2244994945", - "6253282" - ], - "lang": "en", - "is_ticketed": false, - "invited_user_ids": [ - "2244994945", - "6253282" - ], - "participant_count": 420, - "scheduled_start": "2021-07-14T08:00:00.000Z", - "speaker_ids": [ - "2244994945", - "6253282" - ], - "started_at": "2021-07-14T08:00:12.000Z", - "title": "Say hello to the Space data object!", - "updated_at": "2021-07-11T14:44:44.000Z" - }, - "includes": { - "users": [ - { - "id": "2244994945", - "name": "Twitter Dev", - "username": "TwitterDev" - }, - { - "id": "6253282", - "name": "Twitter API", - "username": "TwitterAPI" - } - ] - } -} -``` - -### List - -The list object contains [Twitter Lists](https://help.x.com/en/using-twitter/twitter-lists) metadata describing the referenced List. The List object is the primary object returned in the List lookup endpoint. When requesting additional List fields on this endpoint, simply use the fields parameter `list.fields`. - -The List object is not found as a child of other data objects. However, user objects can be found and expanded in the user resource. These objects are available for expansion by adding `owner_id` to the `expansions` query parameter. Use this expansion with the `list.fields` field parameter when requesting additional fields to complete the primary List object and `user.fields` to complete the expansion object. - -| Field Value | Type | Description | How it can be used | -|:---------------|:-----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------| -| id (default) | string | The unique identifier of this List.
`"id": "2244994945"` | Use this to programmatically retrieve information about a specific List. | -| name (default)| string | The name of the List, as defined when creating the List.
`"name": "Twitter Lists"` | | -| created_at | date (ISO 8601) | The UTC datetime when the List was created.
`"created_at": "2013-12-14T04:35:55.000Z"` | Determine how long a List has been on Twitter. | -| description | string | A brief description to inform users about the List.
`"description": "People that are active members of the Bay area cycling community on Twitter."` | | -| follower_count| integer | Shows how many users follow this List.
`"follower_count": 198` | | -| member_count | integer | Shows how many members are part of this List.
`"member_count": 60` | | -| private | boolean | Indicates if the List is private.
`"private": false` | | -| owner_id | string | Unique identifier of this List's owner.
`"owner_id": "1255542774432063488"` | Can be used to find out if this user owns other Lists and expand User objects. | - -**Retrieving a User Object** - -**Sample Request** - -In the following request, we are requesting fields for the user on the [List lookup by ID](/x-api/lists/list-lookup/introduction) endpoint. Replace `$BEARER_TOKEN` with your generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -```bash -curl --request GET 'https://api.x.com/2/lists/1355797419175383040?list.fields=created_at,description,private,follower_count,member_count,owner_id&expansions=owner_id' --header 'Authorization: Bearer $BEARER_TOKEN' -``` - -** Sample Response** -``` -{ - "data": { - "name": "Twitter Comms", - "member_count": 60, - "id": "1355797419175383040", - "private": false, - "description": "", - "follower_count": 198, - "owner_id": "257366942", - "created_at": "2021-01-31T08:37:48.000Z" - }, - "includes": { - "users": [ - { - "created_at": "2011-02-25T07:51:26.000Z", - "name": "Ashleigh Hay 🤸🏼‍♀️", - "id": "257366942", - "username": "shleighhay", - "verified": false - } - ] - } -} -``` - -### Media - -Media refers to any image, GIF, or video attached to a Tweet. The media object is not a primary object on any endpoint, but can be found and expanded in the Tweet object. The object is available for expansion with `?expansions=attachments.media_keys` to get the condensed object with only default fields. Use the expansion with the field parameter: `media.fields` when requesting additional fields to complete the object. - -| Field value | Type | Description | How it can be used | -|:----------------------------|:---------|:--------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------| -| media_key (default) | string | Unique identifier of the expanded media content.
` "media_key": "13_1263145212760805376"` | Can be used to programmatically retrieve media | -| type (default) | string | Type of content (animated_gif, photo, video).
` "type": "video"` | Classify the media as a photo, GIF, or video | -| url | string | A direct URL to the media file on Twitter. | Returns a Media object with a URL field for photos | -| duration_ms | integer | Available when type is video. Duration in milliseconds of the video.
` "duration_ms": 46947` | | -| height | integer | Height of this content in pixels.
` "height": 1080` | | -| non_public_metrics | object | Non-public engagement metrics for the media content at the time of the request. Requires user context authentication.
` "non_public_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183,}` | Determine video engagement: how many users played through to each quarter of the video. | -| organic_metrics | object | Engagement metrics for the media content, tracked in an organic context, at the time of the request. Requires user context authentication.
` "organic_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183, "view_count": 629}` | Determine organic media engagement. | -| preview_image_url | string | URL to the static placeholder preview of this content.
` "preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg"` | | -| promoted_metrics | object | Engagement metrics for the media content, tracked in a promoted context, at the time of the request. Requires user context authentication.
` "promoted_metrics": { "playback_0_count": 259, "playback_100_count": 15, "playback_25_count": 113, "playback_50_count": 57, "playback_75_count": 25, "view_count": 124}` | Determine media engagement when the Tweet was promoted. | -| public_metrics | object | Public engagement metrics for the media content at the time of the request.
` "public_metrics": { "view_count": 6865141}` | Determine total number of views for the video attached to the Tweet. | -| width | integer | Width of this content in pixels.
` "width": 1920` | | -| alt_text | string | A description of an image to enable and support accessibility. Can be up to 1000 characters long. Alt text can only be added to images at the moment.
` "alt_text": "Rugged hills along the Na Pali coast on the island of Kauai"` | Can be used to provide a written description of an image in case a user is visually impaired. | -| variants | array | Each media object may have multiple display or playback variants, with different resolutions or formats.
` "variants": [{ "bit_rate": 632000, "content_type": "video/mp4", "url": "https://video.twimg.com/ext_tw_video/1527322141724532740/pu/vid/320x568/lnBaR2hCqE-R_90a.mp4?tag=12"}]` | | - -**Retrieving a media object** - -**Sample Request** - -In the following request, we are requesting fields for the media object attached to the Tweet on the [Tweet lookup](/x-api/posts/lookup/introduction) endpoint. Since media is a child object of a Tweet, the `attachment.media_keys` expansion is required. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -```bash -curl --request GET 'https://api.x.com/2/tweets?ids=1263145271946551300&expansions=attachments.media_keys&media.fields=duration_ms,height,media_key,preview_image_url,public_metrics,type,url,width,alt_text' --header 'Authorization: Bearer $BEARER_TOKEN' -``` - -``` -{ - "data": [ - { - "text": "Testing, testing...\n\nA new way to have a convo with exactly who you want. We’re starting with a small % globally, so keep your 👀 out to see it in action. https://t.co/pV53mvjAVT", - "id": "1263145271946551300", - "attachments": { - "media_keys": [ - "13_1263145212760805376" - ] - } - } - ], - "includes": { - "media": [ - { - "duration_ms": 46947, - "type": "video", - "height": 1080, - "media_key": "13_1263145212760805376", - "public_metrics": { - "view_count": 6909260 - }, - "preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg", - "width": 1920 - } - ] - } -} -``` - -### Poll - -A poll included in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet object. The object is available for expansion with `?expansions=attachments.poll_ids` to get the condensed object with only default fields. Use the expansion with the field parameter: `poll.fields` when requesting additional fields to complete the object. - -| Field value | Type | Description | -|:-------------------|:----------------------|:-------------------------------------------------------------------------------------------------------------| -| id (default) | string | Unique identifier of the expanded poll. | -| | | `{"id": "1199786642791452673"}` | -| options (default) | array | Contains objects describing each choice in the referenced poll. | -| | | `{"options": [ { "position": 1, "label": "“C Sharp”", "votes": 795 }, { "position": 2, "label": "“C Hashtag”", "votes": 156 } ]}` | -| duration_minutes | integer | Specifies the total duration of this poll. | -| | | `{"duration_minutes": 1440}` | -| end_datetime | date (ISO 8601) | Specifies the end date and time for this poll. | -| | | `{"end_datetime": "2019-11-28T20:26:41.000Z"}` | -| voting_status | string | Indicates if this poll is still active and can receive votes, or if the voting is now closed. | -| | | `{"voting_status": "closed"}` | - -**Retrieving a poll object** - -**Sample Request** - -In the following request, we are requesting fields for the poll object attached to the Tweet on the [Tweets lookup](/x-api/posts/lookup/introduction) endpoint. Since poll is a child object of a Tweet, the `attachments.poll_id` expansion is required. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -```bash -curl --request GET 'https://api.x.com/2/tweets?ids=1199786642791452673&expansions=attachments.poll_ids&poll.fields=duration_minutes,end_datetime,id,options,voting_status' --header 'Authorization: Bearer $BEARER_TOKEN' -``` - -**Sample Response** - -``` -{ - "data": [ - { - "text": "C#", - "id": "1199786642791452673", - "attachments": { - "poll_ids": [ - "1199786642468413448" - ] - } - } - ], - "includes": { - "polls": [ - { - "id": "1199786642468413448", - "voting_status": "closed", - "duration_minutes": 1440, - "options": [ - { - "position": 1, - "label": "“C Sharp”", - "votes": 795 - }, - { - "position": 2, - "label": "“C Hashtag”", - "votes": 156 - } - ], - "end_datetime": "2019-11-28T20:26:41.000Z" - } - ] - } -} -``` - -### Place - -The place tagged in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet resource. The object is available for expansion with `?expansions=geo.place_id` to get the condensed object with only default fields. Use the expansion with the field parameter: `place.fields` when requesting additional fields to complete the object. - -| Field value | Type | Description | How it can be used | -|:---------------------|:--------|:----------------------------------------------------------------------------------------------|:------------------------------------------------| -| full_name (default) | string | A longer-form detailed place name. | Classify a Tweet by a specific place name | -| | | `"full_name": "Manhattan, NY"` | | -| id (default) | string | The unique identifier of the expanded place, if this is a point of interest tagged in the Tweet. | Use this to programmatically retrieve a place | -| | | `"id": "01a9a39529b27f36"` | | -| contained_within | array | Returns the identifiers of known places that contain the referenced place. | | -| country | string | The full-length name of the country this place belongs to. | Classify a Tweet by country name | -| | | `"country": "United States"` | | -| country_code | string | The ISO Alpha-2 country code this place belongs to. | Classify a Tweet by country code | -| | | `"country_code": "US"` | | -| geo | object | Contains place details in GeoJSON format. | | -| | | ```json | -| | | "geo": | -| | | "type": "Feature", | -| | | "bbox": [ | -| | | -74.026675, | -| | | 40.683935, | -| | | -73.910408, | -| | | 40.877483 | -| | | ], | -| | | "properties": {} | -| | | } | -| | | ``` | | -| name | string | The short name of this place. | Classify a Tweet by a specific place name | -| | | `"name": "Manhattan"` | | -| place_type | string | Specified the particular type of information represented by this place information, such as a city name, or a point of interest. | Classify a Tweet by a specific type of place | -| | | `"place_type": "city"` | | - -**Retrieving a place object** - -**Sample Request** - -In the following request, we are requesting fields for the place object attached to the Tweet on the [Tweets lookup](/x-api/posts/lookup/introduction) endpoint. Since place is a child object of a Tweet, the `geo.place_id` expansion is required. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -```bash -curl --request GET 'https://api.x.com/2/tweets?ids=1136048014974423040&expansions=geo.place_id&place.fields=contained_within,country,country_code,full_name,geo,id,name,place_type' --header 'Authorization: Bearer $BEARER_TOKEN' -``` - -**Sample Response** - -``` -{ - "data": [ - { - "text": "We’re sharing a live demo of the new Twitter Developer Labs program, led by a member of our DevRel team, @jessicagarson #TapIntoTwitter https://t.co/ghv7f4dW5M", - "id": "1136048014974423040", - "geo": { - "place_id": "01a9a39529b27f36" - } - } - ], - "includes": { - "places": [ - { - "geo": { - "type": "Feature", - "bbox": [ - -74.026675, - 40.683935, - -73.910408, - 40.877483 - ], - "properties": {} - }, - "country_code": "US", - "name": "Manhattan", - "id": "01a9a39529b27f36", - "place_type": "city", - "country": "United States", - "full_name": "Manhattan, NY" - } - ] - } -} -``` - -### Direct Message events - -Direct Message (DM) conversations are made up of events. The X API v2 currently supports three event types: MessageCreate, ParticipantsJoin, and ParticipantsLeave. - -DM event objects are returned by the [Direct Message lookup](/x-api/direct-messages/lookup/introduction) endpoints, and a MessageCreate event is created when Direct Messages are successfully created with the [Manage Direct Messages](/x-api/direct-messages/lookup/introduction) endpoints. - -When requesting DM events, there are three default event object attributes, or fields, included: id, event_type, and text. To receive additional event fields, use the [fields](/x-api/fundamentals/fields) parameter dm_event.fields to select others. Other available event fields include the following: dm\_conversation\_id, created_at, sender_id, attachments, participant_ids, and referenced_tweets. - -Several of these fields provide the IDs of other X objects related to the Direct Message event: - -* sender_id - The ID of the account that sent the message, or who invited a participant to a group conversation -* partricipants_ids - An array of account IDs. For ParticipantsJoin and ParticipantsLeave events this array will contain a single ID of the account that created the event -* attachments - Provides media IDs for content that has been uploaded to Twitter by the sender -* referenced_tweets - If a Tweet URL is found in the text field, the ID of that Tweet is included in the response - -The sender_id, participant_ids, referenced_tweets.id, and attachments.media_keys [expansions](/x-api/fundamentals/expansions) are available to expand on these Twitter object IDs. - -| | | | | -| :--- | :--- | :--- | :--- | -| **Field value** | **Type** | **Description** | **How it can be used** | -| id (default) | string | The unique identifier of the event.

"id": "1050118621198921728" | Use this to programmatically retrieve a specific conversation event (available with v1.1 endpoints). | -| event_type (default) | string | Describes the type of event. Three types are currently supported: 

* MessageCreate

* ParticipantsJoin

* ParticipantsLeave


"event_type": "MessageCreate" | When retrieving a conversation's history, understanding when messages were created, and for group conversations, understanding when participants joined and left. All GET methods support filtering on specific event types with the event_type= query parameter. . | -| text (default) | string | The actual UTF-8 text of the Direct Message. 

"text": "Hello, just you!" | With chatbots, this can be used to analyze message contents and determining automated responses. Could be used to build conversation search features. | -| entities | object | Entities that have been parsed out of the text of the DM. | Provides additional information about hashtags, URLs, mentions, etc. | -| sender_id | string | ID of the User creating the event. To expand this object in the response, include sender_id as an expansion  and use the user.fields query parameter to specify User object attributes of interest.

"sender_id": "906948460078698496" | Retrieve the User object of who created the MessageCreate or ParticipantsJoin event. | -| participant_ids | array (of strings) | IDs of the participants joining and leaving a group conversation. Also used when creating new group conversations. To expand this object in the response, include participant_ids as an expansion and use the user.fields query parameter to specify User object attributes of interest.

"participant_ids": \[

     "906948460078698496"

\] | Used to retrieve User objects for participants joining and leaving group conversations. | -| dm\_conversation\_id | string | The unique identifier of the conversation the event is apart of.

"dm\_conversation\_id": "1584988213961031680" | Use this to programmatically retrieve events from a conversation, and add Direct Messages to it. | -| created_at | date (ISO 8601) | Creation time (UTC) of the Tweet.

"created_at": "2019-06-04T23:12:08.000Z" | This field can be used to understand when a Direct Message was created or when conversation participants joined or left. | -| referenced_tweets | array | ID for any Tweet mentioned in the Direct Message text. To expand this object in the response, include referenced_tweets.id as an expansion and use the tweet.fields query parameter to specify Tweet object attributes of interest.

"referenced_tweets": \[

   

"id": "1578868150510456833"

   

\] | When Direct Messages reference a Tweet, these IDs can be used to lookup the Tweet's details. | -| attachments | object | For Direct Messages with attached Media, provides the media key of the uploaded content (photo, video, or GIF). To expand this object in the response, include attachments.media_keys as an expansion and use the media.fields query parameter to specify media object attributes of interest. Currently, one attachment is supported. 

"attachments":

    "media_keys": \[

        "3_1136048009270239232"

    \]

| Understanding the media objects attached to Direct Messages. | - -**Retrieving a Direct Message event object** - -**Sample Request** - -For this example, we will build a request that retrieves events associated with a one-to-one conversation. This request will return fundamental Direct Message event fields, along with additional fields for referenced Tweets and their authors. Let's build a query that asks for: - -* Fundamental event attributes such as when it was created and what conversation it is part of (dm_conversation). -* The account ID and description of who sent the Direct Message. -* The text of any referenced Tweet, and when it was posted. -* The account ID and description of any referenced Tweet author. - -To return those attributes, your request query would include the following: - - `?dm_event.fields=id,sender_id,text,created_at,dm_conversation_id&expansions=sender_id,referenced_tweets.id&tweet.fields=created_at,text,author_id&user.fields=description` - - - ```bash - curl --request GET 'https://api.x.com/2/dm_conversations/with/:participant_id/dm_events?tweet.fields=created_at,text,author_id&user.fields=description&expansions=sender_id,participant_ids,referenced_tweets.id&dm_event.fields=id,sender_id,text,participant_ids,created_at,' - --header 'Authorization: Bearer $BEARER_TOKEN' - ``` - -Be sure to replace $BEARER_TOKEN with your own generated [Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token). - -**Sample Response** - - ``` - { - "data": [{ - "id": "1585047616894574596", - "sender_id": "944480690", - "text": "Hello, just you!", - "created_at": "2022-10-25T23:16:15.000Z", - "event_type": "MessageCreate", - "dm_conversation_id": "944480690-906948460078698496" - }, - { - "id": "1581048670673260549", - "sender_id": "944480690", - "text": "Simple Tweet link: https://t.co/IYFbRIdXHg", - "referenced_tweets": [{ - "id": "1578900353814519810" - }], - "created_at": "2022-10-14T22:25:52.000Z", - "event_type": "MessageCreate", - "dm_conversation_id": "944480690-906948460078698496" - }, - { - "id": "1580705121553420292", - "sender_id": "944480690", - "text": "Adding a new 1-to-1 Direct Message.", - "created_at": "2022-10-13T23:40:43.000Z", - "event_type": "MessageCreate", - "dm_conversation_id": "944480690-906948460078698496" - } - ], - "includes": { - "users": [{ - "name": "API Demos", - "description": "Hosting TwitterDev integrations... @TwitterDev #DevRel", - "id": "944480690", - "username": "FloodSocial" - }, - { - "name": "the SnowBot", - "description": "Home of the @TwitterDev SnowBot... Serving snow reports, snow photos, and snow research links... Chatbot is currently being remodeled for Twitter APIv2.", - "id": "906948460078698496", - "username": "SnowBotDev" - } - ], - "tweets": [{ - "text": "Feeling kind of bad that I didn’t wish everybody a happy new Colorado Water Year…\n\nHappy Water Year to all my Colorado friends and colleagues, new and old… \n\nMay this be a generous water year, although not too generous…", - "id": "1578900353814519810", - "created_at": "2022-10-09T00:09:13.000Z", - "author_id": "944480690", - "edit_history_tweet_ids": [ - "1578900353814519810" - ] - } - ] - }, - "meta": { - "result_count": 3, - "next_token": "18LAA581J5II7LA00C00ZZZZ", - "previous_token": "1BLC45G1H8CAL5DG0G00ZZZZ" - } -} -``` - -### Community - -Communities are dedicated places for X users to connect, share, and get closer to the discussions they care about most. - -Posts in Communities can be seen by anyone on X, but only others within the Community itself can engage and participate in the discussion. - -The Community object contains relevant metadata about a Community. - -| Field value | Type | Description | | -|:----------------------|:--------------------|:--------------------------------------------------------------------------------------------------|:----------------| -| created_at | date (ISO 8601) | Creation time of the Community. | | -| id | string | The unique identifier of the Community. | | -| name | string | The name of the Community. | | -| description | string | The text of the Community’s description, if provided. | | -| access | string | The access level of the Community.

Can be one of: | | -| | | - `Public` | | -| | | - `Closed` | | -| join_policy | string | The join policy for the Community.

Can be one of: | | -| | | - `Open` | | -| | | - `RestrictedJoinRequestsDisabled` | | -| | | - `RestrictedJoinRequestsRequireAdminApproval` | | -| | | - `RestrictedJoinRequestsRequireModeratorApproval` | | -| | | - `SuperFollowRequired` | | -| member_count | integer | The number of members that have joined the Community. | | - -**Retrieving Community objects** - -**Sample Request** - -In the following request, we are requesting specific fields while searching for a list of Communities based on a provided keyword. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -```bash -curl --location 'https://api.x.com/2/communities/search?query=anime&community.fields=access,created_at,description,id,join_policy,member_count,name' --header 'Authorization: $BEARER_TOKEN' -``` - -**Sample Response** - -``` -{ - "data": [ - { - "id": "Q29tbXVuaXR5OjE3NTg3NDc4MTc2NDI3MDA5MjI=", - "description": "Welcome to the Anime Community! Where anime fans gather to share their favorite shows and discuss everything anime-related.", - "join_policy": "Open", - "access": "Public", - "member_count": 39915, - "name": "Anime Community", - "created_at": "2024-02-17T06:58:50.000Z" - }, - { - "id": "Q29tbXVuaXR5OjE1MDY3OTM5NTMxMDYwNDI4OTE=", - "description": "Join and text about anime 🥰", - "join_policy": "Open", - "access": "Public", - "member_count": 26019, - "name": "Anime World 🌸", - "created_at": "2022-03-24T00:44:07.000Z" - }, - { - "id": "Q29tbXVuaXR5OjE0OTY3NzYyMTU5Mzk1MzQ4NDk=", - "description": "For all anime lovers and creators!", - "join_policy": "Open", - "access": "Public", - "member_count": 5612, - "name": "Anime", - "created_at": "2022-02-24T09:17:13.000Z" - } - ], - "meta": { - "next_token": "7140dibdnow9c7btw481s8m561gat797rboud5r80xvzm" - } -} -``` - -## How to use fields and expansions - -By default, the X API v2 data objects include a small number of default fields when making a request without the use of the [fields](/x-api/fundamentals/fields) or [expansions](/x-api/fundamentals/expansions) parameters. This guide will show you how to use the `fields` and `expansions` query parameters in your request to receive additional objects and fields in your response. - -In this guide, we will be requesting several fields in the following Tweet screenshot. -  - - ![This image includes a screenshot of a Tweet posted by @X. You can see the Tweet text, username, published date and time, source, and public metrics. It also includes a video. ](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/ScreenShotDataDictionaryGuide.png.twimg.1920.png) - -As you can see in the screenshot, there are several visible pieces of information related to the Tweet, including the Tweet author, Tweet metrics, created timestamp, video, and video view count. There are also several pieces of data that are not visible within the screenshot, but are still available to request.  - -When making a request to the API, the default response is simple, containing only the default Tweet fields (id and text). You will also only receive the primary object that returns with the given endpoint that you are using, and not any of the associated data objects that might relate to the primary object. - -This simplicity, along with the fields and expansions parameters, enable you to request only those fields you require, depending on your use case.  -  - -#### Requesting additional fields and objects. - -First off, we will be requesting a [Tweet object](/x-api/fundamentals/data-dictionary#tweet) using a Tweet ID and the [GET /tweets endpoint](/x-api/posts/lookup/introduction). - -Request: - - ```bash - curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969' \ - --header 'Authorization: Bearer $BEARER_TOKEN' - ``` - -Response: - - ``` - { - "data": [ - { - "id": "1260294888811347969", - "text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y" - } - ] -} -``` - - -The following step-by-step guide will show you how to retrieve the additional data we can see in the screenshot. - -1. Identify the additional fields that you would like to request by using our [object model](/x-api/fundamentals/data-dictionary#tweet), or by reviewing the list of fields in the endpoints’ API reference pages. - - In this case, we will be requesting the following additional fields: - attachments, author_id, created_at, public_metrics. - - -2. Build the `tweet.fields` query parameter with the above fields as its value using a comma-separated list: - `?tweet.fields=attachments,author_id,created_at,public_metrics` - -3. Add the query parameter to the GET /tweets request that you made earlier. - -Request: - - `curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics' \ - --header 'Authorization: Bearer $BEARER_TOKEN'` - -Response: -  - - ``` - { - "data": [ - { - "id": "1260294888811347969", - "text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y", - "author_id": "783214", - "public_metrics": { - "retweet_count": 5219, - "reply_count": 1828, - "like_count": 17141, - "quote_count": 3255 - }, - "attachments": { - "media_keys": [ - "13_1260294804770041858" - ] - }, - "created_at": "2020-05-12T19:44:51.000Z" - } - ] -} -``` - - - -4. Next, we are going to request fields related to the video that was included in the Tweet. To do so, we will use the `expansions` parameter with `attachments.media_keys` as the value, and add this to the request. - -?expansions=attachments.media_keys - -Request: -  - - ```bash - curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics&expansions=attachments.media_keys' \ - --header 'Authorization: Bearer $BEARER_TOKEN' - ``` - -Response, with the media object represented in the includes object: -  - - ``` - { - "data": [ - { - "id": "1260294888811347969", - "text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y", - "public_metrics": { - "retweet_count": 5219, - "reply_count": 1828, - "like_count": 17141, - "quote_count": 3255 - }, - "created_at": "2020-05-12T19:44:51.000Z", - "attachments": { - "media_keys": [ - "13_1260294804770041858" - ] - }, - "author_id": "783214" - } - ], - "includes": { - "media": [ - { - "media_key": "13_1260294804770041858", - "type": "video" - } - ] - } -} -``` - - - -5. And finally, we are going to request the view count and duration of the video. These aren’t default fields so we have to specifically request them. Use the `media.fields` parameter with the comma-separated values, `public_metrics` and `duration_ms` in your request. - -?media.fields=public\_metrics,duration\_ms - - -Request: -  - - `curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics&expansions=attachments.media_keys&media.fields=duration_ms,public_metrics' --header 'Authorization: Bearer $BEARER_TOKEN'` - - -Response, which now includes all the data that can be seen in the Tweet screenshot: -  - - ``` - { - "data": [ - { - "id": "1260294888811347969", - "text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y", - "author_id": "783214", - "public_metrics": { - "retweet_count": 5219, - "reply_count": 1828, - "like_count": 17141, - "quote_count": 3255 - }, - "created_at": "2020-05-12T19:44:51.000Z", - "attachments": { - "media_keys": [ - "13_1260294804770041858" - ] - } - } - ], - "includes": { - "media": [ - { - "duration_ms": 36503, - "media_key": "13_1260294804770041858", - "public_metrics": { - "view_count": 1534703 - }, - "type": "video" - } - ] - } -} -``` - - -In total, we included the following parameters in this example: - -* ids=1260294888811347969 -* tweet.fields=attachments,author\_id,created\_at,public_metrics -* expansions=attachments.media_keys -* media.fields=public\_metrics,duration\_ms -   - -When tied together, here is what the full query string looks like: - -``` -?ids=1260294888811347969&tweet.fields=attachments,author\_id,created\_at,public\_metrics&expansions=attachments.media\_keys&media.fields=public\_metrics,duration\_ms -``` - - -## X API v2 Example payloads - -### Tweet - - ```json - { - "data": [ - { - "conversation_id": "1304102743196356610", - "id": "1307025659294674945", - "possibly_sensitive": false, - "public_metrics": { - "retweet_count": 11, - "reply_count": 2, - "like_count": 70, - "quote_count": 1 - }, - "entities": { - "urls": [ - { - "start": 74, - "end": 97, - "url": "https://t.co/oeF3ZHeKQQ", - "expanded_url": "https://dev.to/twitterdev/understanding-the-new-tweet-payload-in-the-twitter-api-v2-1fg5", - "display_url": "dev.to/twitterdev/und…", - "images": [ - { - "url": "https://pbs.twimg.com/news_img/1317156296982867969/2uLfv-Bh?format=jpg&name=orig", - "width": 1128, - "height": 600 - }, - { - "url": "https://pbs.twimg.com/news_img/1317156296982867969/2uLfv-Bh?format=jpg&name=150x150", - "width": 150, - "height": 150 - } - ], - "status": 200, - "title": "Understanding the new Tweet payload in the X API v2", - "description": "X recently announced the new X API v2, rebuilt from the ground up to deliver new features...", - "unwound_url": "https://dev.to/twitterdev/understanding-the-new-tweet-payload-in-the-twitter-api-v2-1fg5" - } - ] - }, - "text": "Here’s an article that highlights the updates in the new Tweet payload v2 https://t.co/oeF3ZHeKQQ", - "in_reply_to_user_id": "2244994945", - "created_at": "2020-09-18T18:36:15.000Z", - "author_id": "2244994945", - "referenced_tweets": [ - { - "type": "replied_to", - "id": "1304102743196356610" - } - ], - "lang": "en", - "source": "Twitter Web App" - } - ], - "includes": { - "users": [ - { - "created_at": "2013-12-14T04:35:55.000Z", - "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/3ZX3TNiZCY", - "expanded_url": "https://developer.x.com/en/community", - "display_url": "developer.x.com/en/community" - } - ] - }, - "description": { - "hashtags": [ - { - "start": 17, - "end": 28, - "tag": "TwitterDev" - }, - { - "start": 105, - "end": 116, - "tag": "TwitterAPI" - } - ] - } - }, - "id": "2244994945", - "verified": true, - "location": "127.0.0.1", - "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", - "pinned_tweet_id": "1293593516040269825", - "username": "TwitterDev", - "public_metrics": { - "followers_count": 513961, - "following_count": 2039, - "tweet_count": 3635, - "listed_count": 1672 - }, - "name": "Twitter Dev", - "url": "https://t.co/3ZX3TNiZCY", - "protected": false - } - ], - "tweets": [ - { - "conversation_id": "1304102743196356610", - "id": "1304102743196356610", - "possibly_sensitive": false, - "public_metrics": { - "retweet_count": 31, - "reply_count": 12, - "like_count": 104, - "quote_count": 4 - }, - "entities": { - "mentions": [ - { - "start": 146, - "end": 158, - "username": "suhemparack" - } - ], - "urls": [ - { - "start": 237, - "end": 260, - "url": "https://t.co/CjneyMpgCq", - "expanded_url": "https://x.com/TwitterDev/status/1304102743196356610/video/1", - "display_url": "pic.x.com/CjneyMpgCq" - } - ], - "hashtags": [ - { - "start": 8, - "end": 19, - "tag": "TwitterAPI" - } - ] - }, - "attachments": { - "media_keys": [ - "13_1303848070984024065" - ] - }, - "text": "The new #TwitterAPI includes some improvements to the Tweet payload. You’re probably wondering — what are the main differences? 🧐\n\nIn this video, @SuhemParack compares the v1.1 Tweet payload with what you’ll find using our v2 endpoints. https://t.co/CjneyMpgCq", - "created_at": "2020-09-10T17:01:37.000Z", - "author_id": "2244994945", - "lang": "en", - "source": "Twitter Media Studio" - } - ] - } -} -``` - - -### Tweet reply - - ```json - { - "data": [ - { - "lang": "en", - "conversation_id": "1296887091901718529", - "text": "See how @PennMedCDH are using Twitter data to understand the COVID-19 health crisis 📊\n\nhttps://t.co/1tdA8uDWes", - "referenced_tweets": [ - { - "type": "replied_to", - "id": "1296887091901718529" - } - ], - "possibly_sensitive": false, - "entities": { - "annotations": [ - { - "start": 30, - "end": 36, - "probability": 0.6318, - "type": "Product", - "normalized_text": "Twitter" - } - ], - "mentions": [ - { - "start": 8, - "end": 19, - "username": "PennMedCDH" - } - ], - "urls": [ - { - "start": 87, - "end": 110, - "url": "https://t.co/1tdA8uDWes", - "expanded_url": "https://developer.x.com/en/use-cases/success-stories/penn", - "display_url": "developer.x.com/en/use-cases/s…", - "status": 200, - "title": "Penn Medicine Center for Digital Health", - "description": "Penn Med Center for Digital Health has created a COVID-19 Twitter map that includes charts detailing sentiment, symptoms reported, state-by-state data cuts, and border data on the COVID-19 outbreak. In addition, their Penn Med With You initiative uses aggregate regional information from Twitter to inform their website and text-messaging service. The service uses this information to disseminate relevant and timely resources.", - "unwound_url": "https://developer.x.com/en/use-cases/success-stories/penn" - } - ] - }, - "id": "1296887316556980230", - "public_metrics": { - "retweet_count": 9, - "reply_count": 3, - "like_count": 26, - "quote_count": 2 - }, - "author_id": "2244994945", - "in_reply_to_user_id": "2244994945", - "context_annotations": [ - { - "domain": { - "id": "46", - "name": "Brand Category", - "description": "Categories within Brand Verticals that narrow down the scope of Brands" - }, - "entity": { - "id": "781974596752842752", - "name": "Services" - } - }, - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - }, - { - "domain": { - "id": "123", - "name": "Ongoing News Story", - "description": "Ongoing News Stories like 'Brexit'" - }, - "entity": { - "id": "1220701888179359745", - "name": "COVID-19" - } - } - ], - "source": "Twitter Web App", - "created_at": "2020-08-21T19:10:05.000Z" - } - ], - "includes": { - "users": [ - { - "created_at": "2013-12-14T04:35:55.000Z", - "id": "2244994945", - "protected": false, - "username": "TwitterDev", - "verified": true, - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/3ZX3TNiZCY", - "expanded_url": "https://developer.x.com/en/community", - "display_url": "developer.x.com/en/community" - } - ] - }, - "description": { - "hashtags": [ - { - "start": 17, - "end": 28, - "tag": "TwitterDev" - }, - { - "start": 105, - "end": 116, - "tag": "TwitterAPI" - } - ] - } - }, - "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", - "pinned_tweet_id": "1293593516040269825", - "public_metrics": { - "followers_count": 513962, - "following_count": 2039, - "tweet_count": 3635, - "listed_count": 1672 - }, - "location": "127.0.0.1", - "name": "Twitter Dev", - "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "url": "https://t.co/3ZX3TNiZCY" - }, - { - "created_at": "2013-07-23T16:58:03.000Z", - "id": "1615654896", - "protected": false, - "username": "PennMedCDH", - "verified": false, - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/7eS9RuwIb9", - "expanded_url": "http://centerfordigitalhealth.upenn.edu/", - "display_url": "centerfordigitalhealth.upenn.edu" - } - ] - }, - "description": { - "mentions": [ - { - "start": 0, - "end": 13, - "username": "PennMedicine" - } - ] - } - }, - "description": "@PennMedicine's Center for Digital Health advances science by researching the implications of the advancement of digital health technology in health care.", - "public_metrics": { - "followers_count": 1348, - "following_count": 455, - "tweet_count": 1288, - "listed_count": 92 - }, - "location": "Philadelphia, PA", - "name": "Penn Med CDH", - "profile_image_url": "https://pbs.twimg.com/profile_images/1067488849725726723/MoO3FQ44_normal.jpg", - "url": "https://t.co/7eS9RuwIb9" - } - ], - "tweets": [ - { - "lang": "en", - "conversation_id": "1296887091901718529", - "text": "Dr. @RainaMerchant and her team at the Penn Medicine CDH are helping build the future of health care.\n\nThe team is using insights from social data in many different ways — ranging from uncovering risk factors to shedding light on public sentiment. 🔎", - "possibly_sensitive": false, - "entities": { - "annotations": [ - { - "start": 39, - "end": 55, - "probability": 0.8274, - "type": "Organization", - "normalized_text": "Penn Medicine CDH" - } - ], - "mentions": [ - { - "start": 4, - "end": 18, - "username": "RainaMerchant" - } - ] - }, - "id": "1296887091901718529", - "public_metrics": { - "retweet_count": 9, - "reply_count": 7, - "like_count": 32, - "quote_count": 0 - }, - "author_id": "2244994945", - "source": "Twitter Web App", - "created_at": "2020-08-21T19:09:12.000Z" - } - ] - } -} -``` - - -### Extended Tweet - - ```json - { - "data": [ - { - "conversation_id": "1296121314218897408", - "id": "1296121314218897408", - "possibly_sensitive": false, - "public_metrics": { - "retweet_count": 54, - "reply_count": 9, - "like_count": 172, - "quote_count": 23 - }, - "entities": { - "urls": [ - { - "start": 192, - "end": 215, - "url": "https://t.co/khXhTurm9x", - "expanded_url": "https://devcommunity.x.com/t/hide-replies-now-available-in-the-new-twitter-api/140996", - "display_url": "devcommunity.com/t/hide-replies…", - "images": [ - { - "url": "https://pbs.twimg.com/news_img/1296121315514957825/3CI24hSI?format=png&name=orig", - "width": 400, - "height": 400 - }, - { - "url": "https://pbs.twimg.com/news_img/1296121315514957825/3CI24hSI?format=png&name=150x150", - "width": 150, - "height": 150 - } - ], - "status": 200, - "title": "Hide replies now available in the new Twitter API", - "description": "Today, we’re happy to announce the general availability of the hide replies endpoint in the new Twitter API. The hide replies endpoint allows you to build tools that help people hide or unhide replies to their Tweets. People manage their replies for many reasons, including to give less attention to comments that are abusive, distracting, misleading, or to make conversations more engaging. Through this endpoint, you can build tools to help people on Twitter hide or unhide replies faster and more...", - "unwound_url": "https://devcommunity.x.com/t/hide-replies-now-available-in-the-new-twitter-api/140996" - } - ], - "hashtags": [ - { - "start": 178, - "end": 189, - "tag": "TwitterAPI" - } - ] - }, - "text": "The hide replies endpoint is launching today! \n\nDevelopers can hide replies to Tweets - a crucial way developers can help improve the health of the public conversation using the #TwitterAPI.\n\nhttps://t.co/khXhTurm9x", - "created_at": "2020-08-19T16:26:16.000Z", - "context_annotations": [ - { - "domain": { - "id": "65", - "name": "Interests and Hobbies Vertical", - "description": "Top level interests and hobbies groupings, like Food or Travel" - }, - "entity": { - "id": "848920371311001600", - "name": "Technology", - "description": "Technology and computing" - } - }, - { - "domain": { - "id": "66", - "name": "Interests and Hobbies Category", - "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" - }, - "entity": { - "id": "848921413196984320", - "name": "Computer programming", - "description": "Computer programming" - } - } - ], - "author_id": "2244994945", - "lang": "en", - "source": "Twitter Web App" - } - ], - "includes": { - "users": [ - { - "created_at": "2013-12-14T04:35:55.000Z", - "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/3ZX3TNiZCY", - "expanded_url": "https://developer.x.com/en/community", - "display_url": "developer.x.com/en/community" - } - ] - }, - "description": { - "hashtags": [ - { - "start": 17, - "end": 28, - "tag": "TwitterDev" - }, - { - "start": 105, - "end": 116, - "tag": "TwitterAPI" - } - ] - } - }, - "id": "2244994945", - "verified": true, - "location": "127.0.0.1", - "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", - "pinned_tweet_id": "1293593516040269825", - "username": "TwitterDev", - "public_metrics": { - "followers_count": 513962, - "following_count": 2039, - "tweet_count": 3635, - "listed_count": 1672 - }, - "name": "Twitter Dev", - "url": "https://t.co/3ZX3TNiZCY", - "protected": false - } - ] - } -} -``` - - -### Tweet with media - - ```json - { - "data": [ - { - "lang": "en", - "conversation_id": "1293593516040269825", - "text": "It’s finally here! 🥁 Say hello to the new #TwitterAPI.\n\nWe’re rebuilding the X API v2 from the ground up to better serve our developer community. And today’s launch is only the beginning.\n\nhttps://t.co/32VrwpGaJw https://t.co/KaFSbjWUA8", - "attachments": { - "media_keys": [ - "7_1293565706408038401" - ] - }, - "possibly_sensitive": false, - "entities": { - "annotations": [ - { - "start": 78, - "end": 88, - "probability": 0.4381, - "type": "Product", - "normalized_text": "Twitter API" - } - ], - "hashtags": [ - { - "start": 42, - "end": 53, - "tag": "TwitterAPI" - } - ], - "urls": [ - { - "start": 195, - "end": 218, - "url": "https://t.co/32VrwpGaJw", - "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/introducing_new_twitter_api.html", - "display_url": "blog.x.com/developer/en_u…", - "images": [ - { - "url": "https://pbs.twimg.com/news_img/1336475659279818754/_cmRh7QE?format=jpg&name=orig", - "width": 1200, - "height": 627 - }, - { - "url": "https://pbs.twimg.com/news_img/1336475659279818754/_cmRh7QE?format=jpg&name=150x150", - "width": 150, - "height": 150 - } - ], - "status": 200, - "title": "Introducing a new and improved X API", - "description": "Introducing the new X API - rebuilt from the ground up to deliver new features faster so developers can help the world connect to the public conversation happening on Twitter.", - "unwound_url": "https://blog.x.com/developer/en_us/topics/tools/2020/introducing_new_twitter_api.html" - }, - { - "start": 219, - "end": 242, - "url": "https://t.co/KaFSbjWUA8", - "expanded_url": "https://x.com/TwitterDev/status/1293593516040269825/video/1", - "display_url": "pic.x.com/KaFSbjWUA8" - } - ] - }, - "id": "1293593516040269825", - "public_metrics": { - "retweet_count": 958, - "reply_count": 171, - "like_count": 2848, - "quote_count": 333 - }, - "author_id": "2244994945", - "context_annotations": [ - { - "domain": { - "id": "46", - "name": "Brand Category", - "description": "Categories within Brand Verticals that narrow down the scope of Brands" - }, - "entity": { - "id": "781974596752842752", - "name": "Services" - } - }, - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - }, - { - "domain": { - "id": "65", - "name": "Interests and Hobbies Vertical", - "description": "Top level interests and hobbies groupings, like Food or Travel" - }, - "entity": { - "id": "848920371311001600", - "name": "Technology", - "description": "Technology and computing" - } - }, - { - "domain": { - "id": "66", - "name": "Interests and Hobbies Category", - "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" - }, - "entity": { - "id": "848921413196984320", - "name": "Computer programming", - "description": "Computer programming" - } - } - ], - "source": "Twitter Web App", - "created_at": "2020-08-12T17:01:42.000Z" - } - ], - "includes": { - "media": [ - { - "height": 720, - "duration_ms": 34875, - "media_key": "7_1293565706408038401", - "type": "video", - "preview_image_url": "https://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", - "public_metrics": { - "view_count": 279438 - }, - "width": 1280 - } - ], - "users": [ - { - "created_at": "2013-12-14T04:35:55.000Z", - "id": "2244994945", - "protected": false, - "username": "TwitterDev", - "verified": true, - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/3ZX3TNiZCY", - "expanded_url": "https://developer.x.com/en/community", - "display_url": "developer.x.com/en/community" - } - ] - }, - "description": { - "hashtags": [ - { - "start": 17, - "end": 28, - "tag": "TwitterDev" - }, - { - "start": 105, - "end": 116, - "tag": "TwitterAPI" - } - ] - } - }, - "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", - "pinned_tweet_id": "1293593516040269825", - "public_metrics": { - "followers_count": 513962, - "following_count": 2039, - "tweet_count": 3635, - "listed_count": 1672 - }, - "location": "127.0.0.1", - "name": "Twitter Dev", - "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "url": "https://t.co/3ZX3TNiZCY" - } - ] - } -}` - - -### Retweet - - `{ - "data": [ - { - "public_metrics": { - "retweet_count": 19, - "reply_count": 0, - "like_count": 0, - "quote_count": 0 - }, - "conversation_id": "1229851574555508737", - "id": "1229851574555508737", - "entities": { - "annotations": [ - { - "start": 28, - "end": 38, - "probability": 0.261, - "type": "Product", - "normalized_text": "Alexa Skill" - }, - { - "start": 44, - "end": 50, - "probability": 0.7332, - "type": "Product", - "normalized_text": "Twitter" - } - ], - "mentions": [ - { - "start": 3, - "end": 15, - "username": "suhemparack" - } - ] - }, - "text": "RT @suhemparack: I built an Alexa Skill for Twitter using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it out her…", - "created_at": "2020-02-18T19:33:59.000Z", - "possibly_sensitive": false, - "author_id": "2244994945", - "referenced_tweets": [ - { - "type": "retweeted", - "id": "1229843515603144704" - } - ], - "context_annotations": [ - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10026792024", - "name": "Amazon" - } - }, - { - "domain": { - "id": "48", - "name": "Product", - "description": "Products created by Brands. Examples: Ford Explorer, Apple iPhone." - }, - "entity": { - "id": "968221983803494400", - "name": "Amazon - Alexa", - "description": "Alexa" - } - }, - { - "domain": { - "id": "46", - "name": "Brand Category", - "description": "Categories within Brand Verticals that narrow down the scope of Brands" - }, - "entity": { - "id": "781974596752842752", - "name": "Services" - } - }, - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - } - ], - "source": "Twitter Web App", - "lang": "en" - } - ], - "includes": { - "users": [ - { - "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "username": "TwitterDev", - "name": "Twitter Dev", - "location": "127.0.0.1", - "url": "https://t.co/3ZX3TNiZCY", - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/3ZX3TNiZCY", - "expanded_url": "https://developer.x.com/en/community", - "display_url": "developer.x.com/en/community" - } - ] - }, - "description": { - "hashtags": [ - { - "start": 17, - "end": 28, - "tag": "TwitterDev" - }, - { - "start": 105, - "end": 116, - "tag": "TwitterAPI" - } - ] - } - }, - "id": "2244994945", - "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", - "verified": true, - "public_metrics": { - "followers_count": 513962, - "following_count": 2039, - "tweet_count": 3635, - "listed_count": 1672 - }, - "pinned_tweet_id": "1293593516040269825", - "created_at": "2013-12-14T04:35:55.000Z", - "protected": false - }, - { - "profile_image_url": "https://pbs.twimg.com/profile_images/1230703695051935747/TbQKe91L_normal.jpg", - "username": "suhemparack", - "name": "Suhem Parack", - "location": "Seattle, WA", - "url": "https://t.co/8IkCzClPCz", - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/8IkCzClPCz", - "expanded_url": "https://developer.x.com", - "display_url": "developer.x.com" - } - ] - }, - "description": { - "mentions": [ - { - "start": 42, - "end": 50, - "username": "Twitter" - } - ] - } - }, - "id": "857699969263964161", - "description": "Developer Relations for Academic Research @Twitter. Talk to me about research with Twitter data. Previously: Amazon Alexa. Views are my own", - "verified": false, - "public_metrics": { - "followers_count": 738, - "following_count": 512, - "tweet_count": 460, - "listed_count": 12 - }, - "pinned_tweet_id": "1296498078233571329", - "created_at": "2017-04-27T20:56:22.000Z", - "protected": false - } - ], - "tweets": [ - { - "public_metrics": { - "retweet_count": 19, - "reply_count": 1, - "like_count": 71, - "quote_count": 6 - }, - "conversation_id": "1229843515603144704", - "id": "1229843515603144704", - "entities": { - "annotations": [ - { - "start": 11, - "end": 21, - "probability": 0.3342, - "type": "Product", - "normalized_text": "Alexa Skill" - }, - { - "start": 27, - "end": 33, - "probability": 0.6727, - "type": "Product", - "normalized_text": "Twitter" - } - ], - "urls": [ - { - "start": 127, - "end": 150, - "url": "https://t.co/l5J8wq748G", - "expanded_url": "https://dev.to/twitterdev/building-an-alexa-skill-for-twitter-using-alexa-presentation-language-1aj0", - "display_url": "dev.to/twitterdev/bui…", - "status": 200, - "unwound_url": "https://dev.to/twitterdev/building-an-alexa-skill-for-twitter-using-alexa-presentation-language-1aj0" - } - ] - }, - "text": "I built an Alexa Skill for Twitter using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it out here 👇\n\nhttps://t.co/l5J8wq748G", - "created_at": "2020-02-18T19:01:58.000Z", - "possibly_sensitive": false, - "author_id": "857699969263964161", - "context_annotations": [ - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10026792024", - "name": "Amazon" - } - }, - { - "domain": { - "id": "48", - "name": "Product", - "description": "Products created by Brands. Examples: Ford Explorer, Apple iPhone." - }, - "entity": { - "id": "968221983803494400", - "name": "Amazon - Alexa", - "description": "Alexa" - } - }, - { - "domain": { - "id": "46", - "name": "Brand Category", - "description": "Categories within Brand Verticals that narrow down the scope of Brands" - }, - "entity": { - "id": "781974596752842752", - "name": "Services" - } - }, - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - } - ], - "source": "Twitter Web App", - "lang": "en" - } - ] - } -}` - - -### Quote Tweet - - `{ - "data": [ - { - "lang": "en", - "conversation_id": "1328399838128467969", - "text": "As planned, the Labs v2 endpoints referenced below have now been retired. Please let us know in the forums if you have questions or need help with the X API v2! https://t.co/JaxttUMmjX", - "referenced_tweets": [ - { - "type": "quoted", - "id": "1327011423252144128" - } - ], - "possibly_sensitive": false, - "entities": { - "annotations": [ - { - "start": 151, - "end": 157, - "probability": 0.8115, - "type": "Product", - "normalized_text": "Twitter" - } - ], - "urls": [ - { - "start": 167, - "end": 190, - "url": "https://t.co/JaxttUMmjX", - "expanded_url": "https://x.com/TwitterDev/status/1327011423252144128", - "display_url": "twitter.com/TwitterDev/sta…" - } - ] - }, - "id": "1328399838128467969", - "public_metrics": { - "retweet_count": 7, - "reply_count": 4, - "like_count": 29, - "quote_count": 1 - }, - "author_id": "2244994945", - "context_annotations": [ - { - "domain": { - "id": "46", - "name": "Brand Category", - "description": "Categories within Brand Verticals that narrow down the scope of Brands" - }, - "entity": { - "id": "781974596752842752", - "name": "Services" - } - }, - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - }, - { - "domain": { - "id": "65", - "name": "Interests and Hobbies Vertical", - "description": "Top level interests and hobbies groupings, like Food or Travel" - }, - "entity": { - "id": "848920371311001600", - "name": "Technology", - "description": "Technology and computing" - } - }, - { - "domain": { - "id": "66", - "name": "Interests and Hobbies Category", - "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" - }, - "entity": { - "id": "848921413196984320", - "name": "Computer programming", - "description": "Computer programming" - } - } - ], - "source": "Twitter Web App", - "created_at": "2020-11-16T18:09:36.000Z" - } - ], - "includes": { - "users": [ - { - "created_at": "2013-12-14T04:35:55.000Z", - "id": "2244994945", - "protected": false, - "username": "TwitterDev", - "verified": true, - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/3ZX3TNiZCY", - "expanded_url": "https://developer.x.com/en/community", - "display_url": "developer.x.com/en/community" - } - ] - }, - "description": { - "hashtags": [ - { - "start": 17, - "end": 28, - "tag": "TwitterDev" - }, - { - "start": 105, - "end": 116, - "tag": "TwitterAPI" - } - ] - } - }, - "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", - "pinned_tweet_id": "1293593516040269825", - "public_metrics": { - "followers_count": 513962, - "following_count": 2039, - "tweet_count": 3635, - "listed_count": 1672 - }, - "location": "127.0.0.1", - "name": "Twitter Dev", - "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "url": "https://t.co/3ZX3TNiZCY" - } - ], - "tweets": [ - { - "lang": "en", - "conversation_id": "1327011423252144128", - "text": "👋 Friendly reminder that Twitter Developer Labs v2 hide replies and recent search will be retired next Monday, November 16! We encourage you to migrate to the new hide replies and recent search endpoints now available in the v2 #TwitterAPI. Details: https://t.co/r6z6CI7kEy", - "possibly_sensitive": false, - "entities": { - "annotations": [ - { - "start": 26, - "end": 50, - "probability": 0.4387, - "type": "Product", - "normalized_text": "Twitter Developer Labs v2" - } - ], - "hashtags": [ - { - "start": 228, - "end": 239, - "tag": "TwitterAPI" - } - ], - "urls": [ - { - "start": 250, - "end": 273, - "url": "https://t.co/r6z6CI7kEy", - "expanded_url": "https://devcommunity.x.com/t/retiring-labs-v2-recent-search-and-hide-replies/145795", - "display_url": "devcommunity.com/t/retiring-lab…", - "images": [ - { - "url": "https://pbs.twimg.com/news_img/1327011425240313856/PkurOyu1?format=jpg&name=orig", - "width": 1200, - "height": 630 - }, - { - "url": "https://pbs.twimg.com/news_img/1327011425240313856/PkurOyu1?format=jpg&name=150x150", - "width": 150, - "height": 150 - } - ], - "status": 200, - "title": "Retiring Labs v2 recent search and hide replies", - "description": "As we said in our Early Access and hide replies announcements, the following Twitter Developer Labs v2 endpoints will be retired on November 16th. Labs v2 recent search Labs v2 hide replies If called, these endpoints will respond with an HTTP 410 status and return no data. Based on your feedback from Labs, we incorporated corresponding functionality into the X API v2. The relevant documentation can be found using the links below. Click here to enroll in v2 access if you haven’t already...", - "unwound_url": "https://devcommunity.x.com/t/retiring-labs-v2-recent-search-and-hide-replies/145795" - } - ] - }, - "id": "1327011423252144128", - "public_metrics": { - "retweet_count": 8, - "reply_count": 2, - "like_count": 33, - "quote_count": 4 - }, - "author_id": "2244994945", - "context_annotations": [ - { - "domain": { - "id": "46", - "name": "Brand Category", - "description": "Categories within Brand Verticals that narrow down the scope of Brands" - }, - "entity": { - "id": "781974596752842752", - "name": "Services" - } - }, - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - }, - { - "domain": { - "id": "65", - "name": "Interests and Hobbies Vertical", - "description": "Top level interests and hobbies groupings, like Food or Travel" - }, - "entity": { - "id": "848920371311001600", - "name": "Technology", - "description": "Technology and computing" - } - }, - { - "domain": { - "id": "66", - "name": "Interests and Hobbies Category", - "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" - }, - "entity": { - "id": "848921413196984320", - "name": "Computer programming", - "description": "Computer programming" - } - } - ], - "source": "Twitter Web App", - "created_at": "2020-11-12T22:12:32.000Z" - } - ] - } -} -``` - - -### Retweeted quote Tweet - - ``` - { - "data": [ - { - "lang": "en", - "conversation_id": "1225470895902412800", - "text": "RT @AureliaSpecker: 📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses…", - "referenced_tweets": [ - { - "type": "retweeted", - "id": "1224709550214873090" - } - ], - "possibly_sensitive": false, - "entities": { - "annotations": [ - { - "start": 42, - "end": 47, - "probability": 0.6999, - "type": "Place", - "normalized_text": "London" - } - ], - "mentions": [ - { - "start": 3, - "end": 18, - "username": "AureliaSpecker" - } - ] - }, - "id": "1225470895902412800", - "public_metrics": { - "retweet_count": 12, - "reply_count": 0, - "like_count": 0, - "quote_count": 0 - }, - "author_id": "2244994945", - "context_annotations": [ - { - "domain": { - "id": "46", - "name": "Brand Category", - "description": "Categories within Brand Verticals that narrow down the scope of Brands" - }, - "entity": { - "id": "781974596752842752", - "name": "Services" - } - }, - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - }, - { - "domain": { - "id": "65", - "name": "Interests and Hobbies Vertical", - "description": "Top level interests and hobbies groupings, like Food or Travel" - }, - "entity": { - "id": "848920371311001600", - "name": "Technology", - "description": "Technology and computing" - } - }, - { - "domain": { - "id": "66", - "name": "Interests and Hobbies Category", - "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" - }, - "entity": { - "id": "848921413196984320", - "name": "Computer programming", - "description": "Computer programming" - } - } - ], - "source": "Twitter for iPhone", - "created_at": "2020-02-06T17:26:44.000Z" - } - ], - "includes": { - "users": [ - { - "created_at": "2013-12-14T04:35:55.000Z", - "id": "2244994945", - "protected": false, - "username": "TwitterDev", - "verified": true, - "entities": { - "url": { - "urls": [ - { - "start": 0, - "end": 23, - "url": "https://t.co/3ZX3TNiZCY", - "expanded_url": "https://developer.x.com/en/community", - "display_url": "developer.x.com/en/community" - } - ] - }, - "description": { - "hashtags": [ - { - "start": 17, - "end": 28, - "tag": "TwitterDev" - }, - { - "start": 105, - "end": 116, - "tag": "TwitterAPI" - } - ] - } - }, - "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", - "pinned_tweet_id": "1293593516040269825", - "public_metrics": { - "followers_count": 513962, - "following_count": 2039, - "tweet_count": 3635, - "listed_count": 1672 - }, - "location": "127.0.0.1", - "name": "Twitter Dev", - "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", - "url": "https://t.co/3ZX3TNiZCY" - }, - { - "created_at": "2013-01-18T23:45:43.000Z", - "id": "1102321381", - "protected": false, - "username": "AureliaSpecker", - "verified": false, - "entities": { - "description": { - "mentions": [ - { - "start": 7, - "end": 17, - "username": "TwitterUK" - }, - { - "start": 86, - "end": 95, - "username": "_dormrod" - } - ] - } - }, - "description": "devrel @TwitterUK • Swiss in London • mother of houseplants • personal hairdresser to @_dormrod", - "pinned_tweet_id": "1253069421322567681", - "public_metrics": { - "followers_count": 1036, - "following_count": 1330, - "tweet_count": 855, - "listed_count": 26 - }, - "location": "London, UK", - "name": "Aurelia Specker", - "profile_image_url": "https://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", - "url": "" - } - ], - "tweets": [ - { - "lang": "en", - "conversation_id": "1224709550214873090", - "text": "📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses Twitter's new search endpoint 🚇 https://t.co/87XIPZmZBJ\n\n#DEVcommunity #Pythontutorial @TwitterDev @TwitterAPI https://t.co/dXrJYvn3hY", - "referenced_tweets": [ - { - "type": "quoted", - "id": "1195000047089389573" - } - ], - "possibly_sensitive": false, - "entities": { - "annotations": [ - { - "start": 22, - "end": 27, - "probability": 0.7075, - "type": "Place", - "normalized_text": "London" - }, - { - "start": 120, - "end": 126, - "probability": 0.7355, - "type": "Product", - "normalized_text": "Twitter" - } - ], - "mentions": [ - { - "start": 206, - "end": 217, - "username": "TwitterDev" - }, - { - "start": 218, - "end": 229, - "username": "TwitterAPI" - } - ], - "hashtags": [ - { - "start": 176, - "end": 189, - "tag": "DEVcommunity" - }, - { - "start": 190, - "end": 205, - "tag": "Pythontutorial" - } - ], - "urls": [ - { - "start": 151, - "end": 174, - "url": "https://t.co/87XIPZmZBJ", - "expanded_url": "https://bit.ly/2OrnrCC", - "display_url": "bit.ly/2OrnrCC", - "status": 200, - "unwound_url": "https://dev.to/twitterdev/migrate-to-twitter-s-newly-released-labs-recent-search-endpoint-3npe" - }, - { - "start": 230, - "end": 253, - "url": "https://t.co/dXrJYvn3hY", - "expanded_url": "https://x.com/AureliaSpecker/status/1195000047089389573", - "display_url": "twitter.com/AureliaSpecker…" - } - ] - }, - "id": "1224709550214873090", - "public_metrics": { - "retweet_count": 12, - "reply_count": 0, - "like_count": 43, - "quote_count": 2 - }, - "author_id": "1102321381", - "context_annotations": [ - { - "domain": { - "id": "46", - "name": "Brand Category", - "description": "Categories within Brand Verticals that narrow down the scope of Brands" - }, - "entity": { - "id": "781974596752842752", - "name": "Services" - } - }, - { - "domain": { - "id": "47", - "name": "Brand", - "description": "Brands and Companies" - }, - "entity": { - "id": "10045225402", - "name": "Twitter" - } - }, - { - "domain": { - "id": "65", - "name": "Interests and Hobbies Vertical", - "description": "Top level interests and hobbies groupings, like Food or Travel" - }, - "entity": { - "id": "848920371311001600", - "name": "Technology", - "description": "Technology and computing" - } - }, - { - "domain": { - "id": "66", - "name": "Interests and Hobbies Category", - "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" - }, - "entity": { - "id": "848921413196984320", - "name": "Computer programming", - "description": "Computer programming" - } - } - ], - "source": "Twitter Web App", - "created_at": "2020-02-04T15:01:25.000Z" - } - ] - } -} -``` diff --git a/enterprise-api/fundamentals/edit-posts.mdx b/enterprise-api/fundamentals/edit-posts.mdx deleted file mode 100644 index 957b9f182..000000000 --- a/enterprise-api/fundamentals/edit-posts.mdx +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Edit Posts -sidebarTitle: Edit Posts -description: Working with edited posts in the X API -keywords: ["edit posts", "edit tweets", "edit history", "post edits", "edit metadata", "edit window"] ---- - -Posts on X can be edited within 30 minutes of posting, up to 5 times. The X API provides full access to edit history and metadata. - ---- - -## Edit rules - -| Rule | Details | -|:-----|:--------| -| **Time window** | 30 minutes from original post | -| **Edit limit** | 5 edits maximum | -| **ID behavior** | Each edit creates a new post ID | -| **Deletion** | Deleting any version deletes the entire chain | - ---- - -## What can't be edited - -Some post types are not editable: - -- Promoted posts (ads) -- Posts with polls -- Replies to others (non-self-thread) -- Reposts (Quote posts *can* be edited) -- Community posts -- Collaborative posts -- Scheduled posts - ---- - -## Edit data in responses - -### Default fields - -All post responses include `edit_history_tweet_ids` by default: - -```json -{ - "data": { - "id": "1234567891", - "text": "Updated text (edited)", - "edit_history_tweet_ids": ["1234567890", "1234567891"] - } -} -``` - -- Single ID = never edited -- Multiple IDs = edit history (oldest first) - -### Edit controls - -Request `edit_controls` for edit status: - -```bash -curl "https://api.x.com/2/tweets/1234567891?tweet.fields=edit_controls" \ - -H "Authorization: Bearer $TOKEN" -``` - -```json -{ - "data": { - "id": "1234567891", - "text": "Updated text (edited)", - "edit_history_tweet_ids": ["1234567890", "1234567891"], - "edit_controls": { - "is_edit_eligible": true, - "editable_until": "2024-01-15T12:30:00.000Z", - "edits_remaining": 3 - } - } -} -``` - -| Field | Description | -|:------|:------------| -| `is_edit_eligible` | Whether the post can be edited | -| `editable_until` | Timestamp when edit window closes | -| `edits_remaining` | Number of edits left (0-5) | - ---- - -## Getting edit history - -Use the `edit_history_tweet_ids` expansion to get full post objects for all versions: - -```bash -curl "https://api.x.com/2/tweets/1234567891?\ -tweet.fields=edit_controls&\ -expansions=edit_history_tweet_ids" \ - -H "Authorization: Bearer $TOKEN" -``` - -```json -{ - "data": { - "id": "1234567891", - "text": "Updated text (edited)", - "edit_history_tweet_ids": ["1234567890", "1234567891"], - "edit_controls": { - "is_edit_eligible": true, - "editable_until": "2024-01-15T12:30:00.000Z", - "edits_remaining": 3 - } - }, - "includes": { - "tweets": [{ - "id": "1234567890", - "text": "Original text (with typo)", - "edit_history_tweet_ids": ["1234567890", "1234567891"], - "edit_controls": { - "is_edit_eligible": true, - "editable_until": "2024-01-15T12:30:00.000Z", - "edits_remaining": 3 - } - }] - } -} -``` - ---- - -## Which version is returned? - -By default, the API returns the **most recent version** of an edited post. - -To get a specific version, request it by its post ID directly: - -```bash -# Get original version -curl "https://api.x.com/2/tweets/1234567890" -H "Authorization: Bearer $TOKEN" - -# Get edited version -curl "https://api.x.com/2/tweets/1234567891" -H "Authorization: Bearer $TOKEN" -``` - ---- - -## Metrics for edited posts - -Each version of an edited post has its own engagement metrics. The metrics are attributed to the version that was visible when the engagement occurred. - ---- - -## Availability - -Edit metadata is available: - -- For all posts created since September 29, 2022 -- On all v2 endpoints that return posts -- Including search, timelines, stream, and lookup - -Posts created before this date do not have edit metadata. - ---- - -## Use cases - - - -Monitor posts for edits and log the differences: - -```python -def check_for_edits(post): - history = post.get("edit_history_tweet_ids", []) - if len(history) > 1: - print(f"Post {post['id']} has been edited {len(history) - 1} times") -``` - - -Display an "edited" badge in your UI: - -```javascript -const isEdited = post.edit_history_tweet_ids?.length > 1; -if (isEdited) { - showEditedBadge(); -} -``` - - -Retrieve the original version of an edited post: - -```python -original_id = post["edit_history_tweet_ids"][0] -original = api.get_tweet(original_id) -``` - - - ---- - -## Next steps - - - - Retrieve posts with edit history. - - - Complete post object reference. - - diff --git a/enterprise-api/fundamentals/expansions.mdx b/enterprise-api/fundamentals/expansions.mdx deleted file mode 100644 index c2aac997d..000000000 --- a/enterprise-api/fundamentals/expansions.mdx +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: Expansions -sidebarTitle: Expansions -description: Include related objects in API responses -keywords: ["expansions", "expand objects", "object expansion", "nested objects", "related objects"] ---- - -Expansions let you include related objects in a single API response. Instead of making multiple requests, get a post and its author, media, or referenced posts in one call. - ---- - -## How expansions work - -When you request an expansion, the API includes the full object in the `includes` section of the response: - -```bash -curl "https://api.x.com/2/tweets/1234567890?expansions=author_id" \ - -H "Authorization: Bearer $TOKEN" -``` - -Response: - -```json -{ - "data": { - "id": "1234567890", - "text": "Hello world!", - "author_id": "2244994945" - }, - "includes": { - "users": [{ - "id": "2244994945", - "name": "X Developers", - "username": "xdevelopers" - }] - } -} -``` - -The `author_id` in `data` links to the user object in `includes`. - ---- - -## Post expansions - -| Expansion | Returns | Use case | -|:----------|:--------|:---------| -| `author_id` | User object | Get post author details | -| `referenced_tweets.id` | Post object(s) | Get quoted/replied-to posts | -| `referenced_tweets.id.author_id` | User object(s) | Get authors of referenced posts | -| `in_reply_to_user_id` | User object | Get user being replied to | -| `attachments.media_keys` | Media object(s) | Get images, videos, GIFs | -| `attachments.poll_ids` | Poll object | Get poll options and votes | -| `geo.place_id` | Place object | Get location details | -| `entities.mentions.username` | User object(s) | Get mentioned users | -| `edit_history_tweet_ids` | Post object(s) | Get previous versions of edited posts | - ---- - -## User expansions - -| Expansion | Returns | Use case | -|:----------|:--------|:---------| -| `pinned_tweet_id` | Post object | Get user's pinned post | - ---- - -## Space expansions - -| Expansion | Returns | Use case | -|:----------|:--------|:---------| -| `creator_id` | User object | Get Space creator | -| `host_ids` | User object(s) | Get Space hosts | -| `speaker_ids` | User object(s) | Get Space speakers | -| `invited_user_ids` | User object(s) | Get invited users | - ---- - -## DM expansions - -| Expansion | Returns | Use case | -|:----------|:--------|:---------| -| `sender_id` | User object | Get message sender | -| `participant_ids` | User object(s) | Get conversation participants | -| `attachments.media_keys` | Media object | Get attached media | -| `referenced_tweets.id` | Post object | Get referenced post | - ---- - -## List expansions - -| Expansion | Returns | Use case | -|:----------|:--------|:---------| -| `owner_id` | User object | Get list owner | - ---- - -## Combining with fields - -Expansions return default fields for each object. To get additional fields, combine expansions with field parameters: - -```bash -curl "https://api.x.com/2/tweets/1234567890?\ -expansions=author_id,attachments.media_keys&\ -user.fields=description,public_metrics&\ -media.fields=url,alt_text" \ - -H "Authorization: Bearer $TOKEN" -``` - -Response: - -```json -{ - "data": { - "id": "1234567890", - "text": "Check out this image!", - "author_id": "2244994945", - "attachments": { - "media_keys": ["3_1234567890"] - } - }, - "includes": { - "users": [{ - "id": "2244994945", - "name": "X Developers", - "username": "xdevelopers", - "description": "The voice of the X Developer Platform", - "public_metrics": { - "followers_count": 570842 - } - }], - "media": [{ - "media_key": "3_1234567890", - "type": "photo", - "url": "https://pbs.twimg.com/media/example.jpg", - "alt_text": "Example image" - }] - } -} -``` - ---- - -## Multiple expansions - -Request multiple expansions as a comma-separated list: - -```bash -expansions=author_id,referenced_tweets.id,attachments.media_keys -``` - ---- - -## Common patterns - - - -Get a post with author, media, and referenced posts: - -```bash -expansions=author_id,attachments.media_keys,referenced_tweets.id -tweet.fields=created_at,public_metrics,conversation_id -user.fields=username,name,profile_image_url -media.fields=url,preview_image_url,type -``` - - -Get replies with their authors: - -```bash -expansions=author_id,in_reply_to_user_id,referenced_tweets.id -tweet.fields=conversation_id,in_reply_to_user_id,created_at -user.fields=username,name -``` - - -Get a user profile with their pinned post: - -```bash -expansions=pinned_tweet_id -user.fields=description,public_metrics,verified -tweet.fields=created_at,public_metrics -``` - - - ---- - -## Linking data and includes - -The objects in `includes` don't contain position information. Link them using IDs: - -```python -# Python example -response = api_call() -post = response["data"] -users = {u["id"]: u for u in response["includes"]["users"]} - -# Get the author -author = users.get(post["author_id"]) -print(f"{author['name']} said: {post['text']}") -``` - -```javascript -// JavaScript example -const { data: post, includes } = response; -const users = Object.fromEntries( - includes.users.map(u => [u.id, u]) -); - -const author = users[post.author_id]; -console.log(`${author.name} said: ${post.text}`); -``` - ---- - -## Next steps - - - - Request specific fields for each object. - - - Complete object schemas. - - diff --git a/enterprise-api/fundamentals/fields.mdx b/enterprise-api/fundamentals/fields.mdx deleted file mode 100644 index dc2aef646..000000000 --- a/enterprise-api/fundamentals/fields.mdx +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Fields -sidebarTitle: Fields -description: Request specific data fields in API responses -keywords: ["fields", "tweet fields", "user fields", "field parameters", "API fields", "data fields", "customize response"] ---- - -The X API v2 returns minimal data by default. Use **fields parameters** to request additional data for each object type. - ---- - -## How fields work - -By default, a post lookup returns only `id`, `text`, and `edit_history_tweet_ids`. To get more data, add field parameters to your request: - -```bash -# Default response - minimal fields -curl "https://api.x.com/2/tweets/1234567890" \ - -H "Authorization: Bearer $TOKEN" - -# With additional fields -curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,author_id" \ - -H "Authorization: Bearer $TOKEN" -``` - ---- - -## Available field parameters - -Each object type has its own fields parameter: - -| Object | Parameter | Documentation | -|:-------|:----------|:--------------| -| Post (Tweet) | `tweet.fields` | [Post fields](/x-api/fundamentals/data-dictionary#tweet) | -| User | `user.fields` | [User fields](/x-api/fundamentals/data-dictionary#user) | -| Media | `media.fields` | [Media fields](/x-api/fundamentals/data-dictionary#media) | -| Poll | `poll.fields` | [Poll fields](/x-api/fundamentals/data-dictionary#poll) | -| Place | `place.fields` | [Place fields](/x-api/fundamentals/data-dictionary#place) | - ---- - -## Example: Post fields - -Request specific post fields with `tweet.fields`: - -```bash -curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,lang" \ - -H "Authorization: Bearer $TOKEN" -``` - -Response: - -```json -{ - "data": { - "id": "1234567890", - "text": "Hello world!", - "edit_history_tweet_ids": ["1234567890"], - "created_at": "2024-01-15T12:00:00.000Z", - "lang": "en", - "public_metrics": { - "retweet_count": 10, - "reply_count": 5, - "like_count": 100, - "quote_count": 2, - "bookmark_count": 3, - "impression_count": 1500 - } - } -} -``` - ---- - -## Example: User fields - -Request specific user fields with `user.fields`: - -```bash -curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \ - -H "Authorization: Bearer $TOKEN" -``` - -Response: - -```json -{ - "data": { - "id": "2244994945", - "name": "X Developers", - "username": "xdevelopers", - "created_at": "2013-12-14T04:35:55.000Z", - "description": "The voice of the X Developer Platform", - "public_metrics": { - "followers_count": 570842, - "following_count": 2048, - "tweet_count": 14052, - "listed_count": 1672 - } - } -} -``` - ---- - -## Fields for related objects - -To get fields on related objects (like the author of a post), you need two things: - -1. An **expansion** to include the related object -2. The **fields parameter** for that object type - -```bash -# Get post with author details -curl "https://api.x.com/2/tweets/1234567890?expansions=author_id&user.fields=description,public_metrics" \ - -H "Authorization: Bearer $TOKEN" -``` - -Response: - -```json -{ - "data": { - "id": "1234567890", - "text": "Hello world!", - "author_id": "2244994945" - }, - "includes": { - "users": [{ - "id": "2244994945", - "name": "X Developers", - "username": "xdevelopers", - "description": "The voice of the X Developer Platform", - "public_metrics": { - "followers_count": 570842, - "following_count": 2048 - } - }] - } -} -``` - -[Learn more about expansions →](/x-api/fundamentals/expansions) - ---- - -## Common field combinations - - - -``` -tweet.fields=created_at,public_metrics,possibly_sensitive -``` - - -``` -user.fields=created_at,description,location,public_metrics,verified -``` - - -``` -tweet.fields=created_at,author_id,conversation_id,in_reply_to_user_id,referenced_tweets -expansions=author_id,referenced_tweets.id -user.fields=username,name -``` - - -``` -tweet.fields=attachments -expansions=attachments.media_keys -media.fields=url,preview_image_url,alt_text,public_metrics -``` - - - ---- - -## Important notes - - -**You cannot request subfields.** When you request `public_metrics`, you get all metrics (likes, reposts, replies, quotes, bookmarks, impressions). You can't request just `public_metrics.like_count`. - - -- Field order in responses may differ from request order -- Missing fields in responses mean the value is `null` or empty -- Some fields require specific authentication (e.g., private metrics need user context) -- Check each endpoint's API reference for available fields - ---- - -## Next steps - - - - Include related objects in responses. - - - Complete field reference for all objects. - - diff --git a/enterprise-api/fundamentals/handling-disconnections.mdx b/enterprise-api/fundamentals/handling-disconnections.mdx deleted file mode 100644 index 75c7af96f..000000000 --- a/enterprise-api/fundamentals/handling-disconnections.mdx +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Handling disconnections -sidebarTitle: Handling disconnections -description: Best practices for detecting and recovering from streaming disconnections -keywords: ["streaming disconnections", "handle disconnections", "reconnect stream", "stream reconnection", "disconnection handling", "stream errors"] ---- - -Learn how to handle disconnections when using X streaming endpoints including [Filtered Stream](/x-api/posts/filtered-stream/introduction), [Volume Streams](/x-api/posts/volume-streams/introduction), [Powerstream](/x-api/powerstream/introduction), and [Compliance Streams](/x-api/compliance/streams/introduction). - -## What is a disconnection? - -Establishing a connection to streaming APIs means making a very long-lived HTTPS request and parsing the response incrementally. When connecting to a streaming endpoint, you should form an HTTPS request and consume the resulting stream for as long as practical. - -X servers will hold the connection open indefinitely, barring: - -- Server-side errors -- Excessive client-side lag -- Network issues -- Routine server maintenance -- Duplicate logins - -With streaming connections, disconnections **will** occur and should be expected. Your application must include reconnection logic. - ---- - -## Why connections disconnect - -Possible reasons for disconnections: - -| Reason | Description | -|:-------|:------------| -| Authentication error | Wrong token or incorrect authentication method | -| Server restart | Code deploy on X side — should be expected and designed around | -| Client too slow | Your client isn't keeping up with volume. The server-side message queue grows too large and the connection closes | -| Quota exceeded | Your account exceeded daily/monthly Post quota | -| Too many connections | You have too many active redundant connections | -| Sudden read stop | The rate of Posts being read drops suddenly | -| Network issues | Connectivity problems between server and client | -| Server maintenance | Temporary server-side issue or scheduled maintenance (check the [status page](https://api.twitterstat.us/)) | - ---- - -## Common disconnection errors - -### Operational disconnect - -```json -{ - "errors": [{ - "title": "operational-disconnect", - "disconnect_type": "UpstreamOperationalDisconnect", - "detail": "This stream has been disconnected upstream for operational reasons.", - "type": "https://api.x.com/2/problems/operational-disconnect" - }] -} -``` - -### Too many connections - -```json -{ - "title": "ConnectionException", - "detail": "This stream is currently at the maximum allowed connection limit.", - "connection_issue": "TooManyConnections", - "type": "https://api.x.com/2/problems/streaming-connection" -} -``` - ---- - -## Detecting disconnections - -The streaming endpoints provide a 20-second keep-alive heartbeat (a newline character). Use this signal to detect disconnections: - -1. Your code should detect when fresh content and the heartbeat stop arriving -2. If no data is received for 20 seconds, trigger reconnection logic -3. Some HTTP clients allow you to specify a read timeout — set this to 20 seconds - ---- - -## Reconnection strategy - -Once an established connection drops, attempt to reconnect immediately. If the reconnect fails, use backoff strategies based on the error type: - -### TCP/IP network errors - -Back off **linearly**. These problems are generally temporary. - -- Increase delay by 250ms each attempt -- Maximum delay: 16 seconds - -### HTTP errors - -Back off **exponentially** for HTTP errors where reconnecting is appropriate. - -- Start with 5 second wait -- Double each attempt -- Maximum delay: 320 seconds - -### Rate limit errors (HTTP 429) - -Back off **exponentially** with longer initial wait. - -- Start with 1 minute wait -- Double each attempt -- Each 429 received increases the wait time until rate limiting expires - ---- - -## Rate limits and usage - -Streaming connection responses return three headers to help you understand limits: - -| Header | Description | -|:-------|:------------| -| `x-rate-limit-limit` | Number of allotted requests during the 15-minute window | -| `x-rate-limit-remaining` | Requests made so far in the 15-minute window | -| `x-rate-limit-reset` | UNIX timestamp when the window resets | - -To track how many Posts have been delivered, implement metering logic on the client side so consumption can be measured and paused if needed. - ---- - -## Reconnection best practices - -### Use a FIFO queue architecture - -Your stream client should insert incoming Posts into a first-in, first-out (FIFO) queue or similar memory structure. A separate process/thread should consume Posts from that queue for parsing and storage. This design scales efficiently when Post volumes change dramatically. - -### Test backoff strategies - -Test your backoff implementation using invalid authorization credentials and examine reconnect attempts. A good implementation will not receive any 429 responses. - -### Issue alerts for multiple reconnects - -If your client reaches its upper threshold of time between reconnects, send notifications so you can triage connection issues. - -### Handle DNS changes - -Ensure your client process honors DNS Time To Live (TTL). Some stacks cache resolved addresses for the process duration and won't pick up DNS changes within the TTL. Aggressive caching leads to service disruptions as X shifts load between IP addresses. - -### Set User-Agent header - -Include your client's version in the `User-Agent` HTTP header. This is critical for diagnosing issues on X's end. If your environment precludes setting `User-Agent`, use the `x-user-agent` header instead. - ---- - -## Next steps - - - - Recover missed data after disconnections - - - Build robust streaming clients - - - Handle high throughput streams - - diff --git a/enterprise-api/fundamentals/high-volume-capacity.mdx b/enterprise-api/fundamentals/high-volume-capacity.mdx deleted file mode 100644 index bccc71c1d..000000000 --- a/enterprise-api/fundamentals/high-volume-capacity.mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Handling high-volume capacity -sidebarTitle: High volume capacity -description: Best practices for handling high-volume streaming data events -keywords: ["high volume", "capacity handling", "stream capacity", "volume management", "high throughput", "scaling stream"] ---- - -Learn how to prepare for high-volume events when using X streaming endpoints including [Filtered Stream](/x-api/posts/filtered-stream/introduction), [Volume Streams](/x-api/posts/volume-streams/introduction), [Powerstream](/x-api/powerstream/introduction), and [Compliance Streams](/x-api/compliance/streams/introduction). - -## Planning for high-volume events - -Major national and global events are often accompanied by dramatic spikes in user activity across social media. Sometimes these events are known in advance: - -- Super Bowl -- Political elections -- New Year's celebrations worldwide - -Other times, spikes are unexpected: - -- Natural disasters -- Unplanned political events -- Pop culture moments -- Health emergencies - -These bursts may be short-lived (seconds) or sustained over several minutes. Proper preparation helps your applications handle these spikes. - ---- - -## Review your stream rules - -Before high-volume events: - -- Certain keywords can skyrocket during events (e.g., brand mentions when a brand sponsors a major sporting event) -- Remove unnecessary or overly generic rules that may generate excessive activity volumes -- Communicate with stakeholders prior to known high-volume events to help them plan appropriately - ---- - -## Stress test your application - -Anticipate that burst volumes may reach **5-10x average daily consumption levels**. Depending on your rules, the increase may be much higher. - -Test your application with simulated high volumes to identify bottlenecks before real events occur. - ---- - -## Understand delivery caps - -Flow and delivery caps are based on your access level: - -| Access Level | Delivery Cap | -|:-------------|:-------------| -| Academic | 250 Posts/second | -| Enterprise | Posts/second set at access level | - ---- - -## Stay connected - -With streams, staying connected is essential to avoid missing data. - -Your client application should: - -1. **Detect disconnects** immediately -2. **Retry connections** using appropriate backoff strategies -3. **Use exponential backoff** if reconnect attempts fail - -See [Handling disconnections](/x-api/fundamentals/handling-disconnections) for detailed reconnection strategies. - ---- - -## Build client-side buffering - -Building a multi-threaded application is key for handling high-volume streams: - -### Recommended architecture - -1. **Stream thread** (lightweight) - - Establishes the streaming connection - - Writes received JSON to a memory structure or buffered stream reader - - Handles incoming data only — no processing - -2. **Memory buffer** - - Grows and shrinks as needed - - Acts as a shock absorber for volume spikes - -3. **Processing thread(s)** (heavy lifting) - - Consumes from the buffer - - Parses JSON - - Prepares database writes - - Handles application logic - -```mermaid actions={false} -flowchart LR - A["Stream Connection
(lightweight)"] --> B["Memory Buffer
(expandable)"] --> C["Processing Thread(s)
(scalable)"] -``` - ---- - -## Consider time zones - -Global events happen in global time zones. Events may occur: - -- After business hours -- Over weekends -- During holidays - -Ensure your team is prepared for spikes outside normal business hours. Consider: - -- Automated alerting systems -- On-call rotations -- Automated scaling responses - ---- - -## Monitoring recommendations - -1. **Track Post volume** in real-time -2. **Set up alerts** for volume thresholds (both increases and decreases) -3. **Monitor buffer sizes** to detect when your processing is falling behind -4. **Compare Post timestamps** to current time to identify lag - ---- - -## Emergency measures - -Implement safeguards for extreme circumstances: - -- **Automated alerts** when volume passes preset thresholds -- **Automated rule deletion** for rules bringing in excessive data -- **Stream disconnection** in extreme circumstances to protect your systems -- **Sampling operators** — add `sample:` to rules to reduce matching volume - ---- - -## Next steps - - - - Build robust streaming clients - - - Reconnect gracefully - - - Build resilient applications - - diff --git a/enterprise-api/fundamentals/metrics.mdx b/enterprise-api/fundamentals/metrics.mdx deleted file mode 100644 index eed792263..000000000 --- a/enterprise-api/fundamentals/metrics.mdx +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: Metrics -sidebarTitle: Metrics -description: Access engagement metrics for posts and media -keywords: ["metrics", "engagement metrics", "tweet metrics", "impressions", "likes", "retweets", "video views", "analytics"] ---- - -The X API provides engagement metrics for posts and media. Access public metrics with any authentication, or private metrics for your own content with user authentication. - ---- - -## Metric types - -| Type | Authentication | Description | -|:-----|:---------------|:------------| -| **Public** | Bearer Token | Visible to anyone (impressions, likes, reposts, replies) | -| **Non-public** | User context | Private metrics (clicks) | -| **Organic** | User context | Metrics from non-promoted views | -| **Promoted** | User context | Metrics from ad views | - - -**30-day limit**: Non-public, organic, and promoted metrics are only available for posts created within the last 30 days. - - ---- - -## Available metrics - -### Post metrics - -| Metric | Type | Field path | -|:-------|:-----|:-----------| -| Reposts | Public | `public_metrics.retweet_count` | -| Quotes | Public | `public_metrics.quote_count` | -| Likes | Public | `public_metrics.like_count` | -| Replies | Public | `public_metrics.reply_count` | -| Impressions | Public | `public_metrics.impression_count` | -| Bookmarks | Public | `public_metrics.bookmark_count` | -| URL clicks | Non-public | `non_public_metrics.url_link_clicks` | -| Profile clicks | Non-public | `non_public_metrics.user_profile_clicks` | -| Engagements | Non-public | `non_public_metrics.engagements` | - -### Media metrics (videos) - -| Metric | Type | Field path | -|:-------|:-----|:-----------| -| Views | Public | `public_metrics.view_count` | -| Playback 0% | Non-public | `non_public_metrics.playback_0_count` | -| Playback 25% | Non-public | `non_public_metrics.playback_25_count` | -| Playback 50% | Non-public | `non_public_metrics.playback_50_count` | -| Playback 75% | Non-public | `non_public_metrics.playback_75_count` | -| Playback 100% | Non-public | `non_public_metrics.playback_100_count` | - ---- - -## Requesting metrics - -### Public metrics (any auth) - -```bash -curl "https://api.x.com/2/tweets/1234567890?tweet.fields=public_metrics" \ - -H "Authorization: Bearer $TOKEN" -``` - -Response: - -```json -{ - "data": { - "id": "1234567890", - "text": "Hello world!", - "public_metrics": { - "retweet_count": 50, - "reply_count": 12, - "like_count": 234, - "quote_count": 5, - "bookmark_count": 8, - "impression_count": 5432 - } - } -} -``` - -### Private metrics (user context) - -Requires OAuth 1.0a or OAuth 2.0 with user context for posts you own: - -```bash -curl "https://api.x.com/2/tweets/1234567890?tweet.fields=non_public_metrics,organic_metrics" \ - -H "Authorization: OAuth oauth_consumer_key=...,oauth_token=..." -``` - -Response: - -```json -{ - "data": { - "id": "1234567890", - "text": "Hello world!", - "non_public_metrics": { - "impression_count": 5432, - "url_link_clicks": 89, - "user_profile_clicks": 156, - "engagements": 345 - }, - "organic_metrics": { - "impression_count": 5432, - "like_count": 234, - "reply_count": 12, - "retweet_count": 50, - "url_link_clicks": 89, - "user_profile_clicks": 156 - } - } -} -``` - ---- - -## Video metrics - -For video playback metrics, use the media expansion: - -```bash -curl "https://api.x.com/2/tweets/1234567890?\ -tweet.fields=attachments&\ -expansions=attachments.media_keys&\ -media.fields=public_metrics,non_public_metrics" \ - -H "Authorization: OAuth ..." -``` - -Response: - -```json -{ - "data": { - "id": "1234567890", - "text": "Check out this video!", - "attachments": { - "media_keys": ["13_9876543210"] - } - }, - "includes": { - "media": [{ - "media_key": "13_9876543210", - "type": "video", - "public_metrics": { - "view_count": 12543 - }, - "non_public_metrics": { - "playback_0_count": 12543, - "playback_25_count": 9876, - "playback_50_count": 7654, - "playback_75_count": 5432, - "playback_100_count": 3210 - } - }] - } -} -``` - ---- - -## Organic vs. promoted metrics - -If a post was promoted as an ad, metrics split between organic and promoted views: - -| Context | Description | -|:--------|:------------| -| **Organic** | Metrics from normal timeline views | -| **Promoted** | Metrics from paid ad impressions | -| **Public** | Combined total (organic + promoted) | - -Request both to see the breakdown: - -```bash -tweet.fields=public_metrics,organic_metrics,promoted_metrics -``` - ---- - -## Metric definitions - - -Count of times the post appeared on a user's screen. Not unique—the same user viewing twice counts as two impressions. - - - -Number of reposts (retweets). Does not include quote posts. - - - -Number of quote posts (reposts with comment). These are always organic. - - - -Number of times the post has been bookmarked by users. - - - -Aggregated across all posts containing the video. A video reposted in multiple posts has one total view count. - - - -Number of unique users who played through each percentage of the video. Useful for understanding drop-off rates. - - ---- - -## Requirements summary - -| Metric field | Authentication required | -|:-------------|:-----------------------| -| `public_metrics` | Bearer Token (any) | -| `non_public_metrics` | User context (owned posts only) | -| `organic_metrics` | User context (owned posts only) | -| `promoted_metrics` | User context (promoted posts only) | - ---- - -## Next steps - - - - Complete field reference. - - - Set up user context auth. - - diff --git a/enterprise-api/fundamentals/pagination.mdx b/enterprise-api/fundamentals/pagination.mdx deleted file mode 100644 index 9c1506e65..000000000 --- a/enterprise-api/fundamentals/pagination.mdx +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: Pagination -sidebarTitle: Pagination -description: Navigate through large result sets -keywords: ["pagination", "pagination tokens", "next token", "page through results", "cursor pagination"] ---- - -When an API response contains more results than can be returned at once, use pagination to retrieve all pages of data. - ---- - -## How pagination works - -1. Make your initial request with `max_results` -2. Check the response for a `next_token` in the `meta` object -3. If present, make another request with that token as `pagination_token` -4. Repeat until no `next_token` is returned - -```bash -# Initial request -curl "https://api.x.com/2/users/12345/tweets?max_results=100" \ - -H "Authorization: Bearer $TOKEN" - -# Response includes next_token -# {"data": [...], "meta": {"next_token": "abc123", ...}} - -# Next page -curl "https://api.x.com/2/users/12345/tweets?max_results=100&pagination_token=abc123" \ - -H "Authorization: Bearer $TOKEN" -``` - ---- - -## Pagination tokens - -| Token | Description | -|:------|:------------| -| `next_token` | In response `meta`. Use to get the next page. | -| `previous_token` | In response `meta`. Use to go back a page. | -| `pagination_token` | Request parameter. Set to `next_token` or `previous_token` value. | - ---- - -## Response structure - -```json -{ - "data": [ - {"id": "1234", "text": "..."}, - {"id": "1235", "text": "..."} - ], - "meta": { - "result_count": 100, - "next_token": "7140w9gefhslx3", - "previous_token": "77qp89slxjd" - } -} -``` - -When there are no more results, `next_token` is omitted: - -```json -{ - "data": [...], - "meta": { - "result_count": 42, - "previous_token": "77qp89abc" - } -} -``` - ---- - -## Pagination parameters - -| Parameter | Description | Default | -|:----------|:------------|:--------| -| `max_results` | Results per page | Endpoint-specific | -| `pagination_token` | Token from previous response | None | - -Check each endpoint's API reference for specific `max_results` limits. - ---- - -## Example: Paginating through all results - - - -```python -import requests - -def get_all_tweets(user_id, bearer_token): - url = f"https://api.x.com/2/users/{user_id}/tweets" - headers = {"Authorization": f"Bearer {bearer_token}"} - params = {"max_results": 100} - - all_tweets = [] - - while True: - response = requests.get(url, headers=headers, params=params) - data = response.json() - - if "data" in data: - all_tweets.extend(data["data"]) - - # Check for next page - next_token = data.get("meta", {}).get("next_token") - if not next_token: - break - - params["pagination_token"] = next_token - - return all_tweets -``` - - -```javascript -async function getAllTweets(userId, bearerToken) { - const url = `https://api.x.com/2/users/${userId}/tweets`; - const headers = { Authorization: `Bearer ${bearerToken}` }; - - let allTweets = []; - let paginationToken = null; - - do { - const params = new URLSearchParams({ max_results: 100 }); - if (paginationToken) { - params.set("pagination_token", paginationToken); - } - - const response = await fetch(`${url}?${params}`, { headers }); - const data = await response.json(); - - if (data.data) { - allTweets.push(...data.data); - } - - paginationToken = data.meta?.next_token; - } while (paginationToken); - - return allTweets; -} -``` - - - ---- - -## Best practices - - - - Request the maximum allowed `max_results` to minimize API calls. - - - The last page may have fewer results than `max_results`. - - - Save `next_token` if you need to resume pagination later. - - - For new data, use `since_id` instead of paginating repeatedly. - - - ---- - -## Result ordering - -Results are returned in **reverse chronological order**: - -- First result on first page = most recent -- Last result on last page = oldest - -This applies within and across pages. - ---- - -## Notes - -- Pagination tokens are opaque strings—don't parse or modify them -- Tokens may expire after some time -- If you get fewer results than `max_results`, more may still exist (continue until no `next_token`) -- Use [SDKs](/tools-and-libraries) for automatic pagination handling - ---- - -## Next steps - - - - Understand request limits when paginating. - - - Libraries with built-in pagination. - - diff --git a/enterprise-api/fundamentals/post-annotations.mdx b/enterprise-api/fundamentals/post-annotations.mdx deleted file mode 100644 index 9925207dc..000000000 --- a/enterprise-api/fundamentals/post-annotations.mdx +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: Post Annotations -sidebarTitle: Annotations -description: Entity and context annotations for semantic analysis -keywords: ["annotations", "post annotations", "entity annotations", "context annotations", "NER", "named entity recognition", "topics"] ---- - -Annotations provide semantic metadata about post content. X analyzes posts to identify entities (people, places, products) and context (topics, domains) to help you understand and filter content. - ---- - -## Annotation types - -### Entity annotations - -Named-entity recognition (NER) identifies specific mentions in post text: - -| Type | Examples | -|:-----|:---------| -| **Person** | Barack Obama, Elon Musk | -| **Place** | San Francisco, Japan | -| **Product** | iPhone, ChatGPT | -| **Organization** | NASA, Google | -| **Other** | Super Bowl, Diabetes | - -Entity annotations include a confidence score and position in the text. - -### Context annotations - -Semantic analysis that classifies posts by topic and domain: - -- **Domain**: Broad category (Sports, Entertainment, Technology) -- **Entity**: Specific topic within the domain (NBA, Marvel Movies, AI) - -Context annotations help filter and categorize posts without relying on keywords. - ---- - -## Requesting annotations - -Add `context_annotations` and `entities` to your `tweet.fields`: - -```bash -curl "https://api.x.com/2/tweets/1234567890?tweet.fields=context_annotations,entities" \ - -H "Authorization: Bearer $TOKEN" -``` - ---- - -## Response structure - -```json -{ - "data": { - "id": "1234567890", - "text": "Just saw the new Marvel movie - it was amazing!", - "entities": { - "annotations": [ - { - "start": 17, - "end": 22, - "probability": 0.9234, - "type": "Organization", - "normalized_text": "Marvel" - } - ] - }, - "context_annotations": [ - { - "domain": { - "id": "86", - "name": "Movie", - "description": "A film" - }, - "entity": { - "id": "1234567890", - "name": "Marvel Cinematic Universe" - } - }, - { - "domain": { - "id": "65", - "name": "Interests and Hobbies Vertical" - }, - "entity": { - "id": "781974596752842752", - "name": "Entertainment" - } - } - ] - } -} -``` - ---- - -## Entity annotation fields - -| Field | Description | -|:------|:------------| -| `start` | Start position in text | -| `end` | End position in text | -| `probability` | Confidence score (0-1) | -| `type` | Entity type (Person, Place, etc.) | -| `normalized_text` | Standardized entity name | - ---- - -## Context domains - -X uses 80+ domains to categorize posts. Common domains include: - - - -| ID | Domain | -|:---|:-------| -| 3 | TV Shows | -| 4 | TV Episodes | -| 54 | Musician | -| 56 | Actor | -| 86 | Movie | -| 91 | Podcast | - - -| ID | Domain | -|:---|:-------| -| 6 | Sports Events | -| 11 | Sport | -| 12 | Sports Team | -| 26 | Sports League | -| 60 | Athlete | -| 93 | Coach | - - -| ID | Domain | -|:---|:-------| -| 45 | Brand Vertical | -| 46 | Brand Category | -| 47 | Brand | -| 48 | Product | -| 165 | Technology | -| 166 | Stocks | - - -| ID | Domain | -|:---|:-------| -| 10 | Person | -| 13 | Place | -| 29 | Events | -| 35 | Politicians | -| 119 | Holiday | -| 131 | Unified Twitter Taxonomy | - - - - -Domain 131 (Unified Twitter Taxonomy) powers X's Topics feature visible to users on the platform. - - ---- - -## Using annotations in filters - -### Search and filtered stream - -Filter posts by context annotation entity ID: - -```bash -# Posts about a specific entity -context:86.1234567890 - -# Posts in a specific domain -context:86.* -``` - -### Practical examples - -```bash -# Posts about the NBA -query=context:26.852137520 - -# Posts about Apple products -query=context:47.10026792024 - -# Posts about movies -query=context:86.* -``` - ---- - -## Language support - -Annotations are available for multiple languages: - -| Language | Coverage | -|:---------|:---------| -| English | Highest | -| Japanese | High | -| Spanish | High | -| Portuguese | Medium | -| French | Medium | -| Hindi | Medium | - -Coverage varies by domain and market. - ---- - -## Important notes - - -**Not all posts are annotated.** Annotation coverage depends on: -- Language support -- Topic coverage in X's taxonomy -- Semantic richness of the post text - - -- Annotations are not retroactive—only applied when entities are tracked -- The same entity can appear in multiple domains (e.g., a celebrity is both Person and Actor) -- Entity IDs are stable across domains - ---- - -## Resources - - - - CSV of available context annotation entities. - - diff --git a/enterprise-api/fundamentals/post-cap.mdx b/enterprise-api/fundamentals/post-cap.mdx deleted file mode 100644 index 2b6fcb60d..000000000 --- a/enterprise-api/fundamentals/post-cap.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Usage and Billing -sidebarTitle: Usage & Billing -description: Understanding API usage tracking and pay-per-usage billing -keywords: ["usage", "billing", "pay-per-usage", "API usage", "usage tracking", "post consumption", "API costs"] ---- - -X API v2 uses **pay-per-usage** pricing. You're charged based on actual API consumption, tracked at the app level. - ---- - -## How billing works - -| Concept | Description | -|:--------|:------------| -| **Credit-based** | Purchase credits upfront, deducted as you use the API | -| **Per-request pricing** | Different endpoints have different costs | -| **Real-time tracking** | Monitor usage in the Developer Console | - - -Pay-per-usage plans are subject to a monthly cap of 2 million Post reads. If you need higher volume, consider an [Enterprise plan](/forms/enterprise-api-interest). - - ---- - -## Tracked endpoints - -Posts retrieved from these endpoints count toward usage: - -| Category | Endpoints | -|:---------|:----------| -| **Post lookup** | [GET /2/tweets](/x-api/posts/lookup/introduction) | -| **Search** | [Recent search](/x-api/posts/search/introduction), [Full-archive search](/x-api/posts/search/introduction) | -| **Streaming** | [Filtered stream](/x-api/posts/filtered-stream/introduction), [Filtered stream webhooks](/x-api/webhooks/stream/introduction) | -| **Timelines** | [User posts](/x-api/posts/timelines/introduction), [User mentions](/x-api/posts/timelines/introduction) | -| **Engagement** | [Liked posts](/x-api/posts/likes/introduction), [Bookmarks](/x-api/posts/bookmarks/introduction) | -| **Lists** | [List posts](/x-api/lists/list-tweets/introduction) | -| **Spaces** | [Spaces lookup](/x-api/spaces/lookup/introduction) | - ---- - -## Deduplication - - -**Daily deduplication**: If the same post is returned from multiple queries within a day, it only counts once for billing. - - -This means: - -- Retrieving the same post multiple times in one day = 1 charge -- Retrieving a post again the next day = 1 additional charge -- Different posts in the same request = each counts separately - ---- - -## Monitoring usage - -Track your usage in the [Developer Console](https://console.x.com): - -| Metric | Description | -|:-------|:------------| -| **Total usage** | Posts retrieved in the billing period | -| **By endpoint** | Breakdown by endpoint type | -| **By app** | Usage per developer app | -| **Cost tracking** | Real-time cost calculations | -| **Credit balance** | Remaining prepaid credits | - ---- - -## Managing costs - - - - Configure spending limits in the Developer Console. - - - Get notified before hitting budget thresholds. - - - Cache responses to avoid re-fetching the same posts. - - - Use precise filters to retrieve only needed posts. - - - ---- - -## Pricing details - -For current pricing per endpoint and operation, visit the [Developer Console](https://console.x.com). - -Pricing may vary by: - -- Endpoint type (search vs. lookup vs. stream) -- Operation (read vs. write) -- Data scope (recent vs. full-archive) - ---- - -## Enterprise options - -For high-volume needs with custom pricing: - -- Dedicated support -- Volume discounts -- Custom rate limits -- Complete data access - - - - Discuss custom solutions for your needs. - - - ---- - -## FAQs - - -API requests will fail until you purchase more credits. Set up balance alerts to avoid interruption. - - - -No. Pay only for what you use. You can have months with zero usage and zero cost. - - - -Each unique post delivered through filtered stream counts toward usage, subject to daily deduplication. - - - -No. Only successful responses that return data are billed. - - ---- - -## Next steps - - - - View pricing and purchase credits. - - - Understand request limits (separate from billing). - - diff --git a/enterprise-api/fundamentals/rate-limits.mdx b/enterprise-api/fundamentals/rate-limits.mdx deleted file mode 100644 index 902ca4bf3..000000000 --- a/enterprise-api/fundamentals/rate-limits.mdx +++ /dev/null @@ -1,490 +0,0 @@ ---- -title: X API Rate Limits -sidebarTitle: Rate Limits -description: Per-endpoint rate limits for X API v2 -keywords: ["rate limits", "API rate limits", "request limits", "rate limiting", "throttling", "15 minute window"] ---- - -Rate limits control the number of requests you can make to each endpoint. Exceeding limits results in a 429 error until the window resets. - ---- - -## How rate limits work - -| Concept | Description | -|:--------|:------------| -| **Time window** | Usually 15 minutes or 24 hours | -| **Per-user limits** | Apply with OAuth 1.0a or OAuth 2.0 user tokens | -| **Per-app limits** | Apply with Bearer Token (app-only) | -| **Per-endpoint** | Each endpoint has its own limits | - ---- - -## Checking your limits - -Response headers show your current rate limit status: - -``` -x-rate-limit-limit: 900 -x-rate-limit-remaining: 847 -x-rate-limit-reset: 1705420800 -``` - -| Header | Description | -|:-------|:------------| -| `x-rate-limit-limit` | Maximum requests allowed | -| `x-rate-limit-remaining` | Requests remaining in window | -| `x-rate-limit-reset` | Unix timestamp when window resets | - ---- - -## Rate limit tables - -View the rate limit for each endpoint below. You can also see these limits in the [Developer Console](https://console.x.com). - - -Limits are shown per 15 minutes unless otherwise noted (e.g., "/24hrs" or "/sec"). - - -### Posts (25 endpoints) - -#### Tweets lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/tweets` | 3,500/15min | 5,000/15min | -| GET | `/2/tweets/:id` | 450/15min | 900/15min | - -#### Recent search - -| Method | Endpoint | Per App | Per User | Notes | -|:-------|:---------|:--------|:---------|:------| -| GET | `/2/tweets/search/recent` | 450/15min | 300/15min | 10 default, 100 max results; 512 query length | - -#### Full-archive search - -| Method | Endpoint | Per App | Per User | Notes | -|:-------|:---------|:--------|:---------|:------| -| GET | `/2/tweets/search/all` | 1/sec, 300/15min | 1/sec | 10 default, 500 max results; 1024 query length | - -#### Post counts - -| Method | Endpoint | Per App | Per User | Notes | -|:-------|:---------|:--------|:---------|:------| -| GET | `/2/tweets/counts/recent` | 300/15min | — | 512 query length | -| GET | `/2/tweets/counts/all` | 300/15min | — | 1024 query length | - -#### Filtered stream - -| Method | Endpoint | Per App | Per User | Notes | -|:-------|:---------|:--------|:---------|:------| -| GET | `/2/tweets/search/stream` | 50/15min | — | 1 connection; 1000 rules; 1024 rule length; 250 posts/sec | -| GET | `/2/tweets/search/stream/rules` | 450/15min | — | 1 connection; 1000 rules; 1024 rule length | -| POST | `/2/tweets/search/stream/rules` | 100/15min | — | 1 connection; 1000 rules; 1024 rule length | - -#### Manage posts - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/tweets` | 10,000/24hrs | 100/15min | -| DELETE | `/2/tweets/:id` | — | 50/15min | - -#### Timelines - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/users/:id/tweets` | 10,000/15min | 900/15min | -| GET | `/2/users/:id/mentions` | 450/15min | 300/15min | -| GET | `/2/users/:id/timelines/reverse_chronological` | — | 180/15min | - -#### Likes lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/tweets/:id/liking_users` | 75/15min | 75/15min | -| GET | `/2/users/:id/liked_tweets` | 75/15min | 75/15min | - -#### Manage likes - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/users/:id/likes` | — | 50/15min, 1,000/24hrs | -| DELETE | `/2/users/:id/likes/:tweet_id` | — | 50/15min, 1,000/24hrs | - -#### Retweets lookup - -| Method | Endpoint | Per App | Per User | Notes | -|:-------|:---------|:--------|:---------|:------| -| GET | `/2/tweets/:id/retweeted_by` | 75/15min | 75/15min | — | -| GET | `/2/tweets/:id/quote_tweets` | 75/15min | 75/15min | — | -| GET | `/2/users/reposts_of_me` | — | 75/15min | 100 max results | - -#### Manage retweets - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/users/:id/retweets` | — | 50/15min | -| DELETE | `/2/users/:id/retweets/:tweet_id` | — | 50/15min | - -#### Hide replies - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| PUT | `/2/tweets/:tweet_id/hidden` | — | 50/15min | - ---- - -### Users (14 endpoints) - -#### Users lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/users` | 300/15min | 900/15min | -| GET | `/2/users/:id` | 300/15min | 900/15min | -| GET | `/2/users/by` | 300/15min | 900/15min | -| GET | `/2/users/by/username/:username` | 300/15min | 900/15min | -| GET | `/2/users/me` | — | 75/15min | - -#### Search users - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/users/search` | 300/15min | 900/15min | - -#### Follows lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/users/:id/following` | 300/15min | 300/15min | -| GET | `/2/users/:id/followers` | 300/15min | 300/15min | - -#### Manage follows - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/users/:id/following` | — | 50/15min | -| DELETE | `/2/users/:source_user_id/following/:target_user_id` | — | 50/15min | - -#### Blocks lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/users/:id/blocking` | — | 15/15min | - -#### Mutes lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/users/:id/muting` | — | 15/15min | - -#### Manage mutes - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/users/:id/muting` | — | 50/15min | -| DELETE | `/2/users/:source_user_id/muting/:target_user_id` | — | 50/15min | - ---- - -### Spaces (6 endpoints) - -#### Spaces lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/spaces/:id` | 300/15min | 300/15min | -| GET | `/2/spaces` | 300/15min | 300/15min | -| GET | `/2/spaces/:id/tweets` | 300/15min | 300/15min | -| GET | `/2/spaces/by/creator_ids` | 300/15min, 1/sec | 300/15min, 1/sec | -| GET | `/2/spaces/:id/buyers` | 300/15min | 300/15min | - -#### Search Spaces - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/spaces/search` | 300/15min | 300/15min | - ---- - -### Direct Messages (8 endpoints) - -#### Direct Messages lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/dm_events` | — | 15/15min | -| GET | `/2/dm_events/:id` | — | 15/15min | -| GET | `/2/dm_conversations/:dm_conversation_id/dm_events` | — | 15/15min | -| GET | `/2/dm_conversations/with/:participant_id/dm_events` | — | 15/15min | - -#### Manage Direct Messages - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/dm_conversations` | 1,440/24hrs | 15/15min, 1,440/24hrs | -| POST | `/2/dm_conversations/with/:participant_id/messages` | 1,440/24hrs | 15/15min, 1,440/24hrs | -| POST | `/2/dm_conversations/:dm_conversation_id/messages` | 1,440/24hrs | 15/15min, 1,440/24hrs | -| DELETE | `/2/dm_events/:id` | 4,000/24hrs | 300/15min, 1,500/24hrs | - ---- - -### Lists (14 endpoints) - -#### Lists lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/lists/:id` | 75/15min | 75/15min | -| GET | `/2/users/:id/owned_lists` | 15/15min | 15/15min | - -#### List Tweets lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/lists/:id/tweets` | 900/15min | 900/15min | - -#### List member lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/lists/:id/members` | 900/15min | 900/15min | -| GET | `/2/users/:id/list_memberships` | 75/15min | 75/15min | - -#### Manage Lists - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/lists` | — | 300/15min | -| DELETE | `/2/lists/:id` | — | 300/15min | -| PUT | `/2/lists/:id` | — | 300/15min | - -#### Manage List members - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/lists/:id/members` | — | 300/15min | -| DELETE | `/2/lists/:id/members/:user_id` | — | 300/15min | - -#### Manage List follows - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/users/:id/followed_lists` | — | 50/15min | -| DELETE | `/2/users/:id/followed_lists/:list_id` | — | 50/15min | - -#### Pinned Lists - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/users/:id/pinned_lists` | 15/15min | 15/15min | -| POST | `/2/users/:id/pinned_lists` | — | 50/15min | -| DELETE | `/2/users/:id/pinned_lists/:list_id` | — | 50/15min | - ---- - -### Bookmarks (5 endpoints) - -#### Bookmarks lookup - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/users/:id/bookmarks` | — | 180/15min | -| GET | `/2/users/:id/bookmarks/folders` | 50/15min | 50/15min | -| GET | `/2/users/:id/bookmarks/folders/:folder_id` | 50/15min | 50/15min | - -#### Manage Bookmarks - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/users/:id/bookmarks` | — | 50/15min | -| DELETE | `/2/users/:id/bookmarks/:tweet_id` | — | 50/15min | - ---- - -### Compliance (3 endpoints) - -#### Batch compliance - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/compliance/jobs` | 150/15min | — | -| GET | `/2/compliance/jobs/:job_id` | 150/15min | — | -| GET | `/2/compliance/jobs` | 150/15min | — | - ---- - -### Usage (1 endpoint) - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/usage/tweets` | 50/15min | — | - ---- - -### Trends (2 endpoints) - -#### Personalized Trends - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/users/personalized_trends` | 200/24hrs, 200/15min | 100/24hrs, 10/15min | - -#### Trends by WOEID - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/trends/by/woeid/:id` | 75/15min | — | - ---- - -### Communities (2 endpoints) - -| Method | Endpoint | Per App | Per User | Notes | -|:-------|:---------|:--------|:---------|:------| -| GET | `/2/communities/:id` | 300/15min | 300/15min | — | -| GET | `/2/communities/search` | 300/15min | 300/15min | 100 max results | - ---- - -### Analytics (1 endpoint) - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/tweets/analytics` | 300/15min | 300/15min | - ---- - -### Media (8 endpoints) - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| POST | `/2/media/upload` | 50,000/24hrs | 500/15min | -| GET | `/2/media/upload` | 100,000/24hrs | 1,000/15min | -| POST | `/2/media/upload/initialize` | 180,000/24hrs | 1,875/15min | -| POST | `/2/media/upload/:id/append` | 180,000/24hrs | 1,875/15min | -| POST | `/2/media/upload/:id/finalize` | 180,000/24hrs | 1,875/15min | -| POST | `/2/media/metadata` | 50,000/24hrs | 500/15min | -| POST | `/2/media/subtitles` | 10,000/24hrs | 100/15min | -| DELETE | `/2/media/subtitles` | 10,000/24hrs | 100/15min | - ---- - -### Activity & Webhooks - -| Method | Endpoint | Per App | Per User | Notes | -|:-------|:---------|:--------|:---------|:------| -| GET | `/2/activity/stream` | 450/15min | — | 2 connections; 250 posts/sec | -| POST | `/2/activity/subscriptions` | 500/15min | — | — | -| GET | `/2/activity/subscriptions` | 500/15min | — | — | -| PUT | `/2/activity/subscriptions/:subscription_id` | 500/15min | — | — | -| DELETE | `/2/activity/subscriptions/:subscription_id` | 500/15min | — | — | -| POST | `/2/webhooks` | 450/15min | — | — | -| GET | `/2/webhooks` | 450/15min | — | — | -| PUT | `/2/webhooks/:webhook_id` | 450/15min | — | — | -| DELETE | `/2/webhooks/:webhook_id` | 450/15min | — | — | -| POST | `/2/webhooks/replay` | 100/15min | — | — | - ---- - -### Other endpoints - -| Method | Endpoint | Per App | Per User | -|:-------|:---------|:--------|:---------| -| GET | `/2/tweets/sample10/stream` | 100/15min | — | -| GET | `/2/news/:id` | 200/15min | — | -| GET | `/2/news/search` | 200/15min | 200/15min | -| POST | `/2/users/:id/dm/block` | 25/15min, 1,000/24hrs | 10/15min, 400/24hrs | -| POST | `/2/users/:id/dm/unblock` | 25/15min, 1,000/24hrs | 10/15min, 400/24hrs | -| GET | `/2/users/by/username/:username/tweets` | 1,500/15min | 900/15min | -| GET | `/2/users/by/username/:username/mentions` | 450/15min | 180/15min | -| GET | `/2/users/:id/following/spaces` | 300/15min | 300/15min | -| GET | `/2/tweets/:id/retweets` | 75/15min | 75/15min | -| DELETE | `/2/connections/all` | 25/15min | 25/15min | - ---- - -## Handling rate limits - -When you hit a rate limit, you'll receive a 429 response: - -```json -{ - "errors": [{ - "code": 88, - "message": "Rate limit exceeded" - }] -} -``` - -### Recovery strategy - -1. Check `x-rate-limit-reset` for when the window resets -2. Wait until that time before retrying -3. Use exponential backoff if needed - -```python -import time - -def make_request_with_backoff(url, headers): - response = requests.get(url, headers=headers) - - if response.status_code == 429: - reset_time = int(response.headers.get('x-rate-limit-reset', 0)) - wait_time = max(reset_time - time.time(), 60) - time.sleep(wait_time) - return make_request_with_backoff(url, headers) - - return response -``` - ---- - -## Best practices - - - - Store results locally to reduce repeated requests. - - - For real-time data, use filtered stream instead of polling. - - - Track remaining requests to avoid hitting limits. - - - Distribute requests across the time window. - - - ---- - -## Rate limits vs. billing - -Rate limits and billing are separate: - -| Concept | Purpose | -|:--------|:--------| -| **Rate limits** | Control request frequency for system stability | -| **Usage billing** | Charge for data retrieved (pay-per-usage) | - -You can be within rate limits but still incur usage costs, or hit rate limits without additional cost. - ---- - -## Enterprise rate limits - -Enterprise customers have custom rate limits. Contact your account manager or [apply for Enterprise access](/enterprise/forms/enterprise-api-interest). - ---- - -## Next steps - - - - Handle 429 and other errors. - - - Learn about access levels and features. - - diff --git a/enterprise-api/fundamentals/recovery-and-redundancy.mdx b/enterprise-api/fundamentals/recovery-and-redundancy.mdx deleted file mode 100644 index a87b25e16..000000000 --- a/enterprise-api/fundamentals/recovery-and-redundancy.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: Recovery and redundancy -sidebarTitle: Recovery and redundancy -description: Features for recovering missed data and building resilient streaming applications -keywords: ["recovery", "redundancy", "stream recovery", "reconnect", "fault tolerance", "stream redundancy", "error recovery", "backfill"] ---- - -Learn how to maximize connection time and recover missed data when using X streaming endpoints including [Filtered Stream](/x-api/posts/filtered-stream/introduction), [Firehose Streams](/x-api/stream/stream-all-posts), [Volume Streams](/x-api/posts/volume-streams/introduction), [Powerstream](/x-api/powerstream/introduction), and [Compliance Streams](/x-api/compliance/streams/introduction). - -## Overview - -When consuming streaming data, maximizing connection time and receiving all matched data is a fundamental goal. This requires: - -- Taking advantage of redundant connections -- Automatically detecting disconnections -- Reconnecting quickly -- Having a plan for recovering lost data - ---- - -## Redundant connections - -A redundant connection allows you to establish more than one simultaneous connection to a stream. This provides redundancy by connecting with two separate consumers, receiving the same data through both connections. - -Benefits: -- Hot failover if one stream disconnects -- Protection if your primary server fails -- Continuous data delivery during reconnection - -### How to use - -Simply connect to the same stream URL with a second client. Data will be sent through both connections. - - -Redundant connections are available for Enterprise access. Filtered Stream allows up to two redundant connections for Enterprise projects. Firehose Streams use a `partition` parameter to support up to 20 concurrent connections, while Sample10 (Decahose) supports up to 2 partitions. Check your specific endpoint documentation for connection limits. - - ---- - -## Backfill - -After detecting a disconnection, your system should track how long the disconnection lasted to determine the appropriate recovery method. - -### For disconnections of 5 minutes or less - -Use the **backfill parameter** when reconnecting to receive Posts matched during the disconnection period. - -| Endpoint | Parameter | Example | -|:---------|:----------|:--------| -| Filtered Stream | `backfill_minutes` | `?backfill_minutes=5` | -| Firehose Stream | `backfill_minutes` | `?backfill_minutes=5` | -| Sample Stream (1%) | `backfill_minutes` | `?backfill_minutes=5` | -| Sample10 Stream (Decahose) | `backfill_minutes` | `?backfill_minutes=5` | -| Powerstream | `backfillMinutes` | `?backfillMinutes=5` | - -Example requests: - -**Filtered Stream:** - -```bash -curl 'https://api.x.com/2/tweets/search/stream?backfill_minutes=5' \ - -H "Authorization: Bearer $ACCESS_TOKEN" -``` - -**Firehose Stream:** - -```bash -curl 'https://api.x.com/2/tweets/firehose/stream?backfill_minutes=5&partition=1' \ - -H "Authorization: Bearer $ACCESS_TOKEN" -``` - - -**Important considerations:** -- Older Posts are generally delivered first, before newly matched Posts -- Posts are **not** deduplicated — if you were disconnected for 90 seconds but request 2 minutes of backfill, you'll receive 30 seconds of duplicate Posts -- Your system should be tolerant of duplicates -- Backfill is available with Enterprise access - - ---- - -## Recovery - -For disconnections lasting **longer than 5 minutes**, use the Recovery feature to replay missed data from within the last 24 hours. - -### How Recovery works - -1. Make a connection request with `start_time` and `end_time` parameters -2. Recovery re-streams the specified time period -3. Once complete, the connection disconnects - -### Parameters - -| Parameter | Type | Description | -|:----------|:-----|:------------| -| `start_time` | ISO 8601 date | Start time to recover from (UTC) | -| `end_time` | ISO 8601 date | End time to recover to (UTC) | - -### Example request - -**Filtered Stream:** - -```bash -curl 'https://api.x.com/2/tweets/search/stream?start_time=2022-07-12T15:10:00Z&end_time=2022-07-12T15:20:00Z' \ - -H "Authorization: Bearer $ACCESS_TOKEN" -``` - -**Firehose Stream:** - -```bash -curl 'https://api.x.com/2/tweets/firehose/stream?start_time=2022-07-12T15:10:00Z&end_time=2022-07-12T15:20:00Z&partition=1' \ - -H "Authorization: Bearer $ACCESS_TOKEN" -``` - -**Powerstream:** - -```bash -curl 'https://api.x.com/2/powerstream?startTime=2022-07-12T15:10:00Z&endTime=2022-07-12T15:20:00Z' \ - -H "Authorization: Bearer $ACCESS_TOKEN" -``` - - -**Recovery limits:** -- Available for Enterprise access -- Recovery window: up to 24 hours in the past -- Filtered Stream allows 2 concurrent recovery jobs -- Firehose, Sample10 (Decahose), and language-specific firehose streams also support recovery -- The basic 1% Sample Stream does not support recovery; use the Search endpoint instead - - ---- - -## Alternative recovery: Search - -If you don't have access to backfill or recovery features, or if the disconnection exceeded 24 hours, you can use the [Search Posts endpoint](/x-api/posts/search/introduction) to request missed data. - - -**Matching differences:** -The Search Posts endpoint does not include the `sample:`, `bio:`, `bio_name:`, or `bio_location:` operators, and has certain differences in matching behavior with accents and diacritics. This means you may not fully recover all Posts that would have been received via streaming endpoints. - - ---- - -## Recovery decision tree - -```mermaid actions={false} -flowchart TD - A[Disconnection detected] --> B{How long was the disconnection?} - B -->|5 minutes or less| C[Use backfill parameter] - B -->|5 minutes to 24 hours| D[Use Recovery feature] - B -->|More than 24 hours| E[Use Search Posts endpoint] -``` - ---- - -## Best practices - -1. **Track disconnection duration** — Your system should note when disconnections occur and how long they last - -2. **Implement automatic recovery** — Based on disconnection duration, automatically choose the appropriate recovery method - -3. **Handle duplicates** — Both backfill and recovery may deliver duplicate Posts; implement deduplication logic - -4. **Use redundant connections** — Prevent data loss by maintaining multiple connections when available - -5. **Monitor recovery jobs** — Track the status and completion of recovery operations - ---- - -## Next steps - - - - Detect and handle disconnections - - - Build robust streaming clients - - - Handle high throughput streams - - diff --git a/enterprise-api/fundamentals/response-codes-and-errors.mdx b/enterprise-api/fundamentals/response-codes-and-errors.mdx deleted file mode 100644 index c67925884..000000000 --- a/enterprise-api/fundamentals/response-codes-and-errors.mdx +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: Response Codes & Errors -sidebarTitle: Response Codes -description: HTTP status codes and error handling for the X API -keywords: ["response codes", "error codes", "HTTP status codes", "API errors", "error handling", "debugging"] ---- - -import { Button } from '/snippets/button.mdx'; - -The X API uses standard HTTP status codes. Successful requests return 2xx codes; errors return 4xx or 5xx codes with details in the response body. - ---- - -## HTTP status codes - -### Success codes - -| Code | Meaning | Description | -|:-----|:--------|:------------| -| **200** | OK | Request successful | -| **201** | Created | Resource created (POST requests) | -| **204** | No Content | Success with no response body (DELETE requests) | - -### Client error codes - -| Code | Meaning | Common causes | -|:-----|:--------|:--------------| -| **400** | Bad Request | Invalid JSON, malformed query, missing required parameters | -| **401** | Unauthorized | Invalid or missing authentication credentials | -| **403** | Forbidden | Valid auth but no permission for this resource or action | -| **404** | Not Found | Resource doesn't exist or has been deleted | -| **409** | Conflict | Stream has no rules (filtered stream only) | -| **429** | Too Many Requests | Rate limit or usage cap exceeded | - -### Server error codes - -| Code | Meaning | What to do | -|:-----|:--------|:-----------| -| **500** | Internal Server Error | Wait and retry; check [status page](/status) | -| **502** | Bad Gateway | Wait and retry | -| **503** | Service Unavailable | X is overloaded; wait and retry | -| **504** | Gateway Timeout | Wait and retry | - ---- - -## Error response format - -Error responses include structured details: - -```json -{ - "title": "Invalid Request", - "detail": "The 'query' parameter is required.", - "type": "https://api.x.com/2/problems/invalid-request" -} -``` - -| Field | Description | -|:------|:------------| -| `type` | URI identifying the error type | -| `title` | Short error description | -| `detail` | Specific explanation for this error | - -Additional fields may be present depending on the error type. - ---- - -## Error types - -| Type | Description | -|:-----|:------------| -| `about:blank` | Generic error (see HTTP status code) | -| `.../invalid-request` | Malformed request or invalid parameters | -| `.../resource-not-found` | Post, user, or other resource doesn't exist | -| `.../not-authorized-for-resource` | No access to private/protected content | -| `.../client-forbidden` | App not enrolled or lacks required access | -| `.../usage-capped` | Usage cap exceeded | -| `.../rate-limit-exceeded` | Rate limit exceeded | -| `.../streaming-connection` | Stream connection problem | -| `.../rule-cap` | Too many filtered stream rules | -| `.../invalid-rules` | Rule syntax error | -| `.../duplicate-rules` | Rule already exists | - ---- - -## Partial errors - -Some requests can partially succeed. A 200 response may include both `data` and `errors`: - -```json -{ - "data": [ - {"id": "123", "text": "Hello"} - ], - "errors": [ - { - "resource_id": "456", - "resource_type": "tweet", - "title": "Not Found Error", - "detail": "Could not find tweet with id: [456].", - "type": "https://api.x.com/2/problems/resource-not-found" - } - ] -} -``` - -This happens when requesting multiple resources and some are unavailable. - ---- - -## Troubleshooting common errors - - -**Check your authentication:** -- Verify you're using the correct authentication method for the endpoint -- Ensure credentials haven't been regenerated -- Check the `Authorization` header format -- For OAuth 1.0a, verify signature calculation - -[Authentication guide →](/resources/fundamentals/authentication/overview) - - - -**Check your access:** -- Verify your app has access to this endpoint -- Some endpoints require specific enrollment or approval -- User-context endpoints need appropriate OAuth scopes -- The resource may be private or protected - - - -**Rate limited:** -- Check `x-rate-limit-reset` header for when to retry -- Implement exponential backoff -- Consider caching responses -- Spread requests across the time window - -[Rate limits guide →](/x-api/fundamentals/rate-limits) - - - -**Fix your request:** -- Validate JSON syntax -- Check for missing required parameters -- Verify parameter types (strings vs. numbers) -- Escape special characters in queries - - - -**Check these factors:** -- Protected accounts' posts are only visible with authorization -- Deleted posts return 404 -- Some posts are withheld in certain regions -- Verify search query syntax is correct - - - -**Handle reconnection:** -- Implement automatic reconnect with backoff -- Use recovery features for missed data -- Check for full-buffer disconnects (client not consuming fast enough) -- Verify at least one stream rule exists - -[Streaming guide →](/x-api/posts/filtered-stream/integrate/handling-disconnections) - - ---- - -## Rate limit headers - -Every response includes rate limit information: - -``` -x-rate-limit-limit: 900 -x-rate-limit-remaining: 847 -x-rate-limit-reset: 1705420800 -``` - -| Header | Description | -|:-------|:------------| -| `x-rate-limit-limit` | Max requests in current window | -| `x-rate-limit-remaining` | Requests remaining | -| `x-rate-limit-reset` | Unix timestamp when window resets | - ---- - -## Best practices - - - - Always check HTTP status before parsing the response body. - - - Check for `errors` array even in 200 responses. - - - Use exponential backoff for 429 and 5xx errors. - - - Include request ID and timestamp for debugging. - - - ---- - -## Getting help - -When posting questions about errors, include: - -- The API endpoint URL -- Request headers (sanitize credentials) -- Full error response -- What you expected to happen -- Steps you've tried - - - - Ask questions and search solutions. - - - Check for known issues. - - diff --git a/enterprise-api/fundamentals/versioning.mdx b/enterprise-api/fundamentals/versioning.mdx deleted file mode 100644 index 2a21613c8..000000000 --- a/enterprise-api/fundamentals/versioning.mdx +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: Versioning -sidebarTitle: Versioning -description: X API versioning strategy and deprecation policy -keywords: ["versioning", "API versioning", "API versions", "v2 API", "deprecation", "API changes", "migration"] ---- - -The X API uses version numbers in endpoint paths to provide stability while allowing for evolution. Understanding our versioning strategy helps you plan integrations and stay current. - ---- - -## Current versions - -| Version | Status | Description | -|:--------|:-------|:------------| -| **v2** | Current | Modern endpoints, flexible pricing, all new features | -| **v1.1** | Legacy | Limited support, minimal updates | -| **Enterprise** | Available | High-volume access with dedicated support | - - -Use **X API v2** for all new projects. This is where all new features ship. - - ---- - -## Version in URLs - -The version number appears in the endpoint path: - -``` -https://api.x.com/2/tweets - ^ - version -``` - ---- - -## Breaking vs. non-breaking changes - -### Breaking changes (require code updates) - -These changes only occur in major version bumps: - -- Removing an endpoint -- Removing a response field -- Removing a query parameter -- Adding a new required parameter -- Changing a field's data type -- Renaming a field or resource -- Changing response codes or error types -- Modifying authorization scopes - -### Non-breaking changes (additive) - -These can happen at any time without version changes: - -- Adding a new endpoint -- Adding a new optional parameter -- Adding a new response field -- Adding new OAuth scopes -- Changing error message text -- Nulling fields for privacy/security reasons - ---- - -## Release schedule - -| Type | Frequency | Notice | -|:-----|:----------|:-------| -| **Major versions** | No more than annually | Migration guides provided | -| **Non-breaking changes** | Ongoing | Changelog updates | -| **Security patches** | As needed | May be applied to current version | - ---- - -## Deprecation policy - -When we release a new major version: - -1. **Deprecation**: Previous version is marked deprecated -2. **Support period**: Deprecated version continues to work for a defined period -3. **Retirement**: Deprecated version is removed - -### Definitions - -| Status | Meaning | -|:-------|:--------| -| **Active** | Fully supported with new features and fixes | -| **Deprecated** | No new features; critical bugs only; use discouraged | -| **Retired** | No longer accessible | - ---- - -## Staying informed - -Get notified about changes: - - - - All platform changes and updates. - - - Breaking change notices. - - - Platform news and updates. - - - Monthly digest. - - - ---- - -## Migration resources - -When a new version is released, we provide: - -- **Migration guides**: Step-by-step upgrade instructions -- **Endpoint mapping**: v1 to v2 equivalents -- **Data format changes**: Object model differences - - - - Current migration guidance. - - - v1 to v2 endpoint mapping. - - - ---- - -## Best practices - - - - Start new projects on the latest version. - - - Subscribe to changelog and forum updates. - - - Test in development before production updates. - - - Don't wait until deprecation to upgrade. - - diff --git a/enterprise-api/general/get-openapi-spec.mdx b/enterprise-api/general/get-openapi-spec.mdx index 43965049f..387afc47a 100644 --- a/enterprise-api/general/get-openapi-spec.mdx +++ b/enterprise-api/general/get-openapi-spec.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/openapi.json ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/lists/add-list-member.mdx b/enterprise-api/lists/add-list-member.mdx index f15a29856..c2c37b790 100644 --- a/enterprise-api/lists/add-list-member.mdx +++ b/enterprise-api/lists/add-list-member.mdx @@ -1,3 +1,5 @@ --- openapi: post /2/lists/{id}/members ---- \ No newline at end of file +--- + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/lists/create-list.mdx b/enterprise-api/lists/create-list.mdx index 95b1c45f4..3bba0f6c5 100644 --- a/enterprise-api/lists/create-list.mdx +++ b/enterprise-api/lists/create-list.mdx @@ -1,3 +1,5 @@ --- openapi: post /2/lists ---- \ No newline at end of file +--- + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/lists/delete-list.mdx b/enterprise-api/lists/delete-list.mdx index 791bf070f..499317053 100644 --- a/enterprise-api/lists/delete-list.mdx +++ b/enterprise-api/lists/delete-list.mdx @@ -1,3 +1,5 @@ --- openapi: delete /2/lists/{id} ---- \ No newline at end of file +--- + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/lists/get-list-by-id.mdx b/enterprise-api/lists/get-list-by-id.mdx index 968001063..440074ee9 100644 --- a/enterprise-api/lists/get-list-by-id.mdx +++ b/enterprise-api/lists/get-list-by-id.mdx @@ -1,3 +1,5 @@ --- openapi: get /2/lists/{id} ---- \ No newline at end of file +--- + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/lists/get-list-followers.mdx b/enterprise-api/lists/get-list-followers.mdx index d06609491..85ede2b04 100644 --- a/enterprise-api/lists/get-list-followers.mdx +++ b/enterprise-api/lists/get-list-followers.mdx @@ -1,3 +1,5 @@ --- openapi: get /2/lists/{id}/followers ---- \ No newline at end of file +--- + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/lists/get-list-members.mdx b/enterprise-api/lists/get-list-members.mdx index fed3c12a8..566b8818d 100644 --- a/enterprise-api/lists/get-list-members.mdx +++ b/enterprise-api/lists/get-list-members.mdx @@ -1,3 +1,5 @@ --- openapi: get /2/lists/{id}/members ---- \ No newline at end of file +--- + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/lists/get-list-posts.mdx b/enterprise-api/lists/get-list-posts.mdx index bca06c29b..6e2ccfe42 100644 --- a/enterprise-api/lists/get-list-posts.mdx +++ b/enterprise-api/lists/get-list-posts.mdx @@ -1,3 +1,5 @@ --- openapi: get /2/lists/{id}/tweets ---- \ No newline at end of file +--- + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/lists/list-lookup/integrate.mdx b/enterprise-api/lists/list-lookup/integrate.mdx index 8e8a4a120..ffc937efa 100644 --- a/enterprise-api/lists/list-lookup/integrate.mdx +++ b/enterprise-api/lists/list-lookup/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating List lookup keywords: ["list lookup integration", "lists integration guide", "list lookup implementation"] --- diff --git a/enterprise-api/lists/list-lookup/migrate/overview.mdx b/enterprise-api/lists/list-lookup/migrate/overview.mdx index 5e3fdb0cf..bd7d3249d 100644 --- a/enterprise-api/lists/list-lookup/migrate/overview.mdx +++ b/enterprise-api/lists/list-lookup/migrate/overview.mdx @@ -4,6 +4,7 @@ sidebarTitle: Overview keywords: ["list lookup migration", "lists lookup migration", "v1.1 to v2 list lookup", "list lookup migration guide", "migrate list lookup"] --- + import { Button } from '/snippets/button.mdx'; ## Comparing X API’s List lookup endpoints diff --git a/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx index 8354da890..fe5bd6ef1 100644 --- a/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx @@ -4,6 +4,7 @@ sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "list lookup migration", "migrate list lookup", "standard to v2 list lookup", "v1 to v2 list lookup", "migration guide"] --- + import { Button } from '/snippets/button.mdx'; ### List lookup: Standard v1.1 compared to X API v2 diff --git a/enterprise-api/lists/list-members/integrate.mdx b/enterprise-api/lists/list-members/integrate.mdx index eab4d1c87..632f9aa81 100644 --- a/enterprise-api/lists/list-members/integrate.mdx +++ b/enterprise-api/lists/list-members/integrate.mdx @@ -8,8 +8,6 @@ import { Button } from '/snippets/button.mdx'; This page covers tools and key concepts for integrating the List members endpoints. ---- - ## Helpful tools Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: diff --git a/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx b/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx index 5aa797089..6ea32f009 100644 --- a/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx +++ b/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx @@ -4,6 +4,7 @@ sidebarTitle: List members lookup keywords: ["list members lookup migration", "v1.1 to v2 list members lookup", "migrate list members lookup", "standard to v2 list members", "list members migration"] --- + import { Button } from '/snippets/button.mdx'; ### List members lookup: Standard v1.1 compared to X API v2 diff --git a/enterprise-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.mdx b/enterprise-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.mdx index ef3d1984e..d79ca3cfb 100644 --- a/enterprise-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.mdx +++ b/enterprise-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.mdx @@ -1,65 +1,66 @@ ---- -title: Manage list members -sidebarTitle: Manage list members -keywords: ["manage list members migration", "v1.1 to v2 manage list members", "migrate manage list members", "standard to v2 list members", "list members migration"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Manage List members: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST lists/members/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create) and [POST lists/members/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage List members endpoints. - -* **Similarities** - * Authentication -* **Differences** - * Endpoint URLs - * App and Project requirements - * HTTP methods - * Rate limits - * Request parameters - -#### Similarities - -**Authentication** - -Both endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage List member endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/lists/members/create.json - (Adds a member to a specified List) - * POST https://api.x.com/1.1/lists/members/destroy.json - (Removes a member from a specified List) -* X API v2 endpoint: - * POST https://api.x.com/2/lists/:id/members - (Adds a member to a specified List) - - * DELETE https://api.x.com/2/lists/:id/members/:user_id - (Removes a member from a specified List) - -**Rate limits** - -| **Standard v1.1** | **X API v2** | -| :--- | :--- | -| /1.1/lists/members/create.json

none | /2/lists/:id/members

300 requests per 15-minute window with OAuth 1.0a User Context

300 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | -| /1.1/lists/members/destroy.json

none | /2/lists/:id/members/:user_id

300 requests per 15-minute window with OAuth 1.0a User Context

300 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps related to a project. - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| **Standard v1.1** | **X API v2** | -| :--- | :--- | -| list_id | id | -| slug | No equivalent | -| screen_name | No equivalent | -| owner\_screen\_name | No equivalent | -| owner_id | No equivalent | +--- +title: Manage list members +sidebarTitle: Manage list members +keywords: ["manage list members migration", "v1.1 to v2 manage list members", "migrate manage list members", "standard to v2 list members", "list members migration"] +--- + + +import { Button } from '/snippets/button.mdx'; + +### Manage List members: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST lists/members/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create) and [POST lists/members/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage List members endpoints. + +* **Similarities** + * Authentication +* **Differences** + * Endpoint URLs + * App and Project requirements + * HTTP methods + * Rate limits + * Request parameters + +#### Similarities + +**Authentication** + +Both endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage List member endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/lists/members/create.json + (Adds a member to a specified List) + * POST https://api.x.com/1.1/lists/members/destroy.json + (Removes a member from a specified List) +* X API v2 endpoint: + * POST https://api.x.com/2/lists/:id/members + (Adds a member to a specified List) + + * DELETE https://api.x.com/2/lists/:id/members/:user_id + (Removes a member from a specified List) + +**Rate limits** + +| **Standard v1.1** | **X API v2** | +| :--- | :--- | +| /1.1/lists/members/create.json

none | /2/lists/:id/members

300 requests per 15-minute window with OAuth 1.0a User Context

300 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | +| /1.1/lists/members/destroy.json

none | /2/lists/:id/members/:user_id

300 requests per 15-minute window with OAuth 1.0a User Context

300 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps related to a project. + +**Request parameters** + +The following standard v1.1 request parameters have equivalents in X API v2: + +| **Standard v1.1** | **X API v2** | +| :--- | :--- | +| list_id | id | +| slug | No equivalent | +| screen_name | No equivalent | +| owner\_screen\_name | No equivalent | +| owner_id | No equivalent | diff --git a/enterprise-api/lists/list-members/migrate/overview.mdx b/enterprise-api/lists/list-members/migrate/overview.mdx index 912e298f5..7019172d3 100644 --- a/enterprise-api/lists/list-members/migrate/overview.mdx +++ b/enterprise-api/lists/list-members/migrate/overview.mdx @@ -4,6 +4,7 @@ sidebarTitle: Overview keywords: ["list members migration", "list members migrate", "v1.1 to v2 list members", "list members migration guide", "migrate list members"] --- + import { Button } from '/snippets/button.mdx'; ## Comparing X API’s List members endpoints diff --git a/enterprise-api/lists/list-tweets/integrate.mdx b/enterprise-api/lists/list-tweets/integrate.mdx index 0bc8b7292..14e0c9c76 100644 --- a/enterprise-api/lists/list-tweets/integrate.mdx +++ b/enterprise-api/lists/list-tweets/integrate.mdx @@ -2,14 +2,14 @@ title: Integration guide sidebarTitle: Integration guide keywords: ["list tweets integration", "list timeline integration", "list tweets guide", "list timeline setup"] + + --- import { Button } from '/snippets/button.mdx'; This page covers tools and key concepts for integrating the List Posts lookup endpoint. ---- - ## Helpful tools Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: diff --git a/enterprise-api/lists/list-tweets/migrate/overview.mdx b/enterprise-api/lists/list-tweets/migrate/overview.mdx index 64c95a0c6..296c5a557 100644 --- a/enterprise-api/lists/list-tweets/migrate/overview.mdx +++ b/enterprise-api/lists/list-tweets/migrate/overview.mdx @@ -4,6 +4,7 @@ sidebarTitle: Overview keywords: ["list tweets migration", "list timeline migration", "v1.1 to v2 list tweets", "list tweets migration guide", "migrate list tweets"] --- + import { Button } from '/snippets/button.mdx'; ## Comparing X API’s List Posts lookup endpoints diff --git a/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx index 8b152748e..1fa4a0b70 100644 --- a/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx @@ -4,6 +4,7 @@ sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "list tweets migration", "migrate list tweets", "standard to v2 list tweets", "v1 to v2 list tweets", "migration guide"] --- + import { Button } from '/snippets/button.mdx'; ### List Posts lookup: Standard v1.1 compared to X API v2 diff --git a/enterprise-api/lists/manage-lists/integrate.mdx b/enterprise-api/lists/manage-lists/integrate.mdx index 9821ee757..dd024151f 100644 --- a/enterprise-api/lists/manage-lists/integrate.mdx +++ b/enterprise-api/lists/manage-lists/integrate.mdx @@ -2,14 +2,14 @@ title: Integration guide sidebarTitle: Integration guide keywords: ["manage lists integration", "list management integration", "lists integration guide", "list management setup"] + + --- import { Button } from '/snippets/button.mdx'; This page covers tools and key concepts for integrating the Lists endpoints. ---- - ## Helpful tools Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: @@ -107,7 +107,6 @@ const client = new Client({ oauth1 }); // Create a new List const response = await client.lists.create({ name: "My List", - description: "A list of interesting accounts", }); console.log(response.data); ``` diff --git a/enterprise-api/lists/manage-lists/migrate/overview.mdx b/enterprise-api/lists/manage-lists/migrate/overview.mdx index aa61273ca..da2be355c 100644 --- a/enterprise-api/lists/manage-lists/migrate/overview.mdx +++ b/enterprise-api/lists/manage-lists/migrate/overview.mdx @@ -4,6 +4,7 @@ sidebarTitle: Overview keywords: ["lists migration", "manage lists migration", "v1.1 to v2 lists", "lists migration guide", "migrate lists"] --- + import { Button } from '/snippets/button.mdx'; ## Comparing X API’s Lists endpoints diff --git a/enterprise-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.mdx index 68b460f36..d43321f5b 100644 --- a/enterprise-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.mdx @@ -1,219 +1,219 @@ ---- -title: v1 to v2 -sidebarTitle: v1 to v2 -keywords: ["v1.1 to v2 migration", "lists migration", "migrate lists", "standard to v2 lists", "v1 to v2 lists", "migration guide"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Manage Lists: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST lists/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-create), [POST lists/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy), and [POST lists/update](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-update) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage List endpoints. - -* **Similarities** - * Authentication -* **Differences** - * Endpoint URLs - * App and Project requirements - * HTTP methods - * Rate limits - * Request parameters - -#### Similarities - -**Authentication** - -Both endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage Lists endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/lists/create.json - (Creates a List) - * POST https://api.x.com/1.1/lists/destroy.json - (Deletes a List) - * POST https://api.x.com/1.1/lists/update.json - (Updates a List) -* X API v2 endpoint: - * POST https://api.x.com/2/lists - (Creates a List) - - * DELETE https://api.x.com/2/lists/:id - (Deletes a List) - - * PUT https://api.x.com/2/lists/:id - (Updates a List) - - - -**Rate limits** - -| **Standard v1.1** | **X API v2** | -| :--- | :--- | -| /1.1/lists/create.json

none | /2/lists

300 requests per 15-minute window with OAuth 1.0a User Context | -| /1.1/lists/destroy.json

none | /2/lists/:id

300 requests per 15-minute window with OAuth 1.0a User Context | -| /1.1/lists/update.json

none | /2/lists/:id

300 requests per 15-minute window with OAuth 1.0a User Context | - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps related to a project. - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -**Create a List** - -| **Standard** | **X API v2** | -| :--- | :--- | -| name | name | -| mode | private | -| description | description | - -**Delete/Update a List** - -| **Standard** | **X API v2** | -| :--- | :--- | -| owner\_screen\_name | No equivalent | -| owner_id | No equivalent | -| list_id | id | -| slug | No equivalent | - - -**Please note:** Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters (for the POST endpoint) or path parameters (for the DELETE and PUT endpoints). - - ---- - -## Code examples - -### Create a List (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/lists" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"name": "My List", "description": "A great list"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/lists" -data = {"name": "My List", "description": "A great list"} - -response = requests.post(url, auth=auth, json=data) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Create a List -response = client.lists.create(name="My List", description="A great list") -print(f"Created List: {response.data.id}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Create a List -const response = await client.lists.create({ - name: "My List", - description: "A great list", -}); -console.log(`Created List: ${response.data?.id}`); -``` - - - -### Delete a List (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/lists/123456789" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/lists/123456789" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Delete a List -response = client.lists.delete("123456789") -print(f"Deleted: {response.data.deleted}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Delete a List -const response = await client.lists.delete("123456789"); -console.log(`Deleted: ${response.data?.deleted}`); -``` - - +--- +title: v1 to v2 +sidebarTitle: v1 to v2 +keywords: ["v1.1 to v2 migration", "lists migration", "migrate lists", "standard to v2 lists", "v1 to v2 lists", "migration guide"] +--- + + +import { Button } from '/snippets/button.mdx'; + +### Manage Lists: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST lists/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-create), [POST lists/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy), and [POST lists/update](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-update) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage List endpoints. + +* **Similarities** + * Authentication +* **Differences** + * Endpoint URLs + * App and Project requirements + * HTTP methods + * Rate limits + * Request parameters + +#### Similarities + +**Authentication** + +Both endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage Lists endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/lists/create.json + (Creates a List) + * POST https://api.x.com/1.1/lists/destroy.json + (Deletes a List) + * POST https://api.x.com/1.1/lists/update.json + (Updates a List) +* X API v2 endpoint: + * POST https://api.x.com/2/lists + (Creates a List) + + * DELETE https://api.x.com/2/lists/:id + (Deletes a List) + + * PUT https://api.x.com/2/lists/:id + (Updates a List) + + + +**Rate limits** + +| **Standard v1.1** | **X API v2** | +| :--- | :--- | +| /1.1/lists/create.json

none | /2/lists

300 requests per 15-minute window with OAuth 1.0a User Context | +| /1.1/lists/destroy.json

none | /2/lists/:id

300 requests per 15-minute window with OAuth 1.0a User Context | +| /1.1/lists/update.json

none | /2/lists/:id

300 requests per 15-minute window with OAuth 1.0a User Context | + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps related to a project. + +**Request parameters** + +The following standard v1.1 request parameters have equivalents in X API v2: + +**Create a List** + +| **Standard** | **X API v2** | +| :--- | :--- | +| name | name | +| mode | private | +| description | description | + +**Delete/Update a List** + +| **Standard** | **X API v2** | +| :--- | :--- | +| owner\_screen\_name | No equivalent | +| owner_id | No equivalent | +| list_id | id | +| slug | No equivalent | + + +**Please note:** Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters (for the POST endpoint) or path parameters (for the DELETE and PUT endpoints). + + +--- + +## Code examples + +### Create a List (v2) + + + +```bash cURL +curl -X POST "https://api.x.com/2/lists" \ + -H "Authorization: OAuth ..." \ + -H "Content-Type: application/json" \ + -d '{"name": "My List", "description": "A great list"}' +``` + +```python Python +# Requires OAuth 1.0a User Context authentication +import requests +from requests_oauthlib import OAuth1 + +auth = OAuth1( + "API_KEY", "API_SECRET", + "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" +) + +url = "https://api.x.com/2/lists" +data = {"name": "My List", "description": "A great list"} + +response = requests.post(url, auth=auth, json=data) +print(response.json()) +``` + +```python Python SDK +from xdk import Client +from xdk.oauth1_auth import OAuth1 + +oauth1 = OAuth1( + api_key="YOUR_API_KEY", + api_secret="YOUR_API_SECRET", + access_token="YOUR_ACCESS_TOKEN", + access_token_secret="YOUR_ACCESS_TOKEN_SECRET" +) + +client = Client(auth=oauth1) + +# Create a List +response = client.lists.create(name="My List", description="A great list") +print(f"Created List: {response.data.id}") +``` + +```javascript JavaScript SDK +import { Client, OAuth1 } from "@xdevplatform/xdk"; + +const oauth1 = new OAuth1({ + apiKey: "YOUR_API_KEY", + apiSecret: "YOUR_API_SECRET", + accessToken: "YOUR_ACCESS_TOKEN", + accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", +}); + +const client = new Client({ oauth1 }); + +// Create a List +const response = await client.lists.create({ + name: "My List", +}); +console.log(`Created List: ${response.data?.id}`); +``` + + + +### Delete a List (v2) + + + +```bash cURL +curl -X DELETE "https://api.x.com/2/lists/123456789" \ + -H "Authorization: OAuth ..." +``` + +```python Python +# Requires OAuth 1.0a User Context authentication +import requests +from requests_oauthlib import OAuth1 + +auth = OAuth1( + "API_KEY", "API_SECRET", + "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" +) + +url = "https://api.x.com/2/lists/123456789" +response = requests.delete(url, auth=auth) +print(response.json()) +``` + +```python Python SDK +from xdk import Client +from xdk.oauth1_auth import OAuth1 + +oauth1 = OAuth1( + api_key="YOUR_API_KEY", + api_secret="YOUR_API_SECRET", + access_token="YOUR_ACCESS_TOKEN", + access_token_secret="YOUR_ACCESS_TOKEN_SECRET" +) + +client = Client(auth=oauth1) + +# Delete a List +response = client.lists.delete("123456789") +print(f"Deleted: {response.data.deleted}") +``` + +```javascript JavaScript SDK +import { Client, OAuth1 } from "@xdevplatform/xdk"; + +const oauth1 = new OAuth1({ + apiKey: "YOUR_API_KEY", + apiSecret: "YOUR_API_SECRET", + accessToken: "YOUR_ACCESS_TOKEN", + accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", +}); + +const client = new Client({ oauth1 }); + +// Delete a List +const response = await client.lists.delete("123456789"); +console.log(`Deleted: ${response.data?.deleted}`); +``` + + diff --git a/enterprise-api/lists/pinned-lists/integrate.mdx b/enterprise-api/lists/pinned-lists/integrate.mdx index 6eeaf10ad..999689256 100644 --- a/enterprise-api/lists/pinned-lists/integrate.mdx +++ b/enterprise-api/lists/pinned-lists/integrate.mdx @@ -2,14 +2,14 @@ title: Integration guide sidebarTitle: Integration guide keywords: ["pinned lists integration", "pin lists integration", "pinned lists guide", "pinned lists setup", "list pinning integration"] + + --- import { Button } from '/snippets/button.mdx'; This page covers tools and key concepts for integrating the pinned Lists endpoints. ---- - ## Helpful tools Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: diff --git a/enterprise-api/lists/remove-list-member.mdx b/enterprise-api/lists/remove-list-member.mdx index 6fb011242..049678047 100644 --- a/enterprise-api/lists/remove-list-member.mdx +++ b/enterprise-api/lists/remove-list-member.mdx @@ -1,3 +1,5 @@ --- openapi: delete /2/lists/{id}/members/{user_id} ---- \ No newline at end of file +--- + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/lists/update-list.mdx b/enterprise-api/lists/update-list.mdx index bdb7eb20f..c47c5440e 100644 --- a/enterprise-api/lists/update-list.mdx +++ b/enterprise-api/lists/update-list.mdx @@ -1,3 +1,5 @@ --- openapi: put /2/lists/{id} ---- \ No newline at end of file +--- + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/llms.txt b/enterprise-api/llms.txt new file mode 100644 index 000000000..21a3b57e6 --- /dev/null +++ b/enterprise-api/llms.txt @@ -0,0 +1,395 @@ +# Enterprise APIs + +> Enterprise-grade APIs: Account Activity webhooks, X Activity (XAA), GNIP 2.0 PowerTrack, historical search, compliance streams, and more. + +## Core +- [Enterprise API](https://docs.x.com/enterprise-api/introduction.md): Enterprise-grade access to X's full firehose, volume streams, and dedicated support +- [Tools And Libraries](https://docs.x.com/enterprise-api/tools-and-libraries.md) +- [What to Build](https://docs.x.com/enterprise-api/what-to-build.md): Ideas and inspiration for building with the X API + +## Account Activity +- [Create Replay Job](https://docs.x.com/enterprise-api/account-activity/create-replay-job.md): Reference documentation for the endpoint and related functionality. +- [Create Subscription](https://docs.x.com/enterprise-api/account-activity/create-subscription.md): Reference documentation for the endpoint and related functionality. +- [Delete Subscription](https://docs.x.com/enterprise-api/account-activity/delete-subscription.md): Reference documentation for the endpoint and related functionality. +- [Get Subscription Count](https://docs.x.com/enterprise-api/account-activity/get-subscription-count.md): Reference documentation for the endpoint and related functionality. +- [Get Subscriptions](https://docs.x.com/enterprise-api/account-activity/get-subscriptions.md): Reference documentation for the endpoint and related functionality. +- [V2 Account Activity API](https://docs.x.com/enterprise-api/account-activity/introduction.md): Receive real-time account activity events via webhooks +- [Quickstart](https://docs.x.com/enterprise-api/account-activity/quickstart.md): Set up Account Activity API subscriptions and start receiving real-time events +- [Validate Subscription](https://docs.x.com/enterprise-api/account-activity/validate-subscription.md): Reference documentation for the endpoint and related functionality. +- [v2 Account Activity API Migration Guide](https://docs.x.com/enterprise-api/account-activity/migrate/overview.md): This guide helps you migrate from the legacy Enterprise Account Activity API to the V2 Account Activity API. The core + +## Activity +- [Activity Stream](https://docs.x.com/enterprise-api/activity/activity-stream.md): Reference documentation for the endpoint and related functionality. +- [Create X Activity Subscription](https://docs.x.com/enterprise-api/activity/create-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. +- [Deletes X Activity Subscription](https://docs.x.com/enterprise-api/activity/deletes-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. +- [Get X Activity Subscriptions](https://docs.x.com/enterprise-api/activity/get-x-activity-subscriptions.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/enterprise-api/activity/introduction.md): The X Activity API (XAA) endpoint group allows developers to tap in to activity events happening on the X Platform. A +- [Quickstart](https://docs.x.com/enterprise-api/activity/quickstart.md): This guide explains how to subscribe for and receive events using the X Activity API endpoints. There generally 3 step +- [Update X Activity Subscription](https://docs.x.com/enterprise-api/activity/update-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. + +## Bookmarks +- [Create Bookmark](https://docs.x.com/enterprise-api/bookmarks/create-bookmark.md): Reference documentation for the endpoint and related functionality. +- [Delete Bookmark](https://docs.x.com/enterprise-api/bookmarks/delete-bookmark.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmark Folders](https://docs.x.com/enterprise-api/bookmarks/get-bookmark-folders.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmarks By Folder Id](https://docs.x.com/enterprise-api/bookmarks/get-bookmarks-by-folder-id.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmarks](https://docs.x.com/enterprise-api/bookmarks/get-bookmarks.md): Reference documentation for the endpoint and related functionality. + +## Chat +- [Add Members To A Chat Group Conversation](https://docs.x.com/enterprise-api/chat/add-members-to-a-chat-group-conversation.md): Reference documentation for the endpoint and related functionality. +- [Add Public Key](https://docs.x.com/enterprise-api/chat/add-public-key.md): Reference documentation for the endpoint and related functionality. +- [Append Chat Media Upload](https://docs.x.com/enterprise-api/chat/append-chat-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Create Chat Group Conversation](https://docs.x.com/enterprise-api/chat/create-chat-group-conversation.md): Reference documentation for the endpoint and related functionality. +- [Download Chat Media](https://docs.x.com/enterprise-api/chat/download-chat-media.md): Reference documentation for the endpoint and related functionality. +- [Finalize Chat Media Upload](https://docs.x.com/enterprise-api/chat/finalize-chat-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Get Chat Conversation](https://docs.x.com/enterprise-api/chat/get-chat-conversation.md): Reference documentation for the endpoint and related functionality. +- [Get Chat Conversations](https://docs.x.com/enterprise-api/chat/get-chat-conversations.md): Reference documentation for the endpoint and related functionality. +- [Get User Public Keys](https://docs.x.com/enterprise-api/chat/get-user-public-keys.md): Reference documentation for the endpoint and related functionality. +- [Initialize Chat Group](https://docs.x.com/enterprise-api/chat/initialize-chat-group.md): Reference documentation for the endpoint and related functionality. +- [Initialize Chat Media Upload](https://docs.x.com/enterprise-api/chat/initialize-chat-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Initialize Conversation Keys](https://docs.x.com/enterprise-api/chat/initialize-conversation-keys.md): Reference documentation for the endpoint and related functionality. +- [Mark Conversation As Read](https://docs.x.com/enterprise-api/chat/mark-conversation-as-read.md): Reference documentation for the endpoint and related functionality. +- [Send Chat Message](https://docs.x.com/enterprise-api/chat/send-chat-message.md): Reference documentation for the endpoint and related functionality. +- [Send Typing Indicator](https://docs.x.com/enterprise-api/chat/send-typing-indicator.md): Reference documentation for the endpoint and related functionality. + +## Communities +- [Get Community By Id](https://docs.x.com/enterprise-api/communities/get-community-by-id.md): Reference documentation for the endpoint and related functionality. +- [Search Communities](https://docs.x.com/enterprise-api/communities/search-communities.md): Reference documentation for the endpoint and related functionality. +- [Communities Lookup](https://docs.x.com/enterprise-api/communities/lookup/introduction.md): Retrieve Community details by ID +- [Communities Search](https://docs.x.com/enterprise-api/communities/search/introduction.md): Search for Communities by keyword + +## Community Notes +- [Create A Community Note](https://docs.x.com/enterprise-api/community-notes/create-a-community-note.md): Reference documentation for the endpoint and related functionality. +- [Delete A Community Note](https://docs.x.com/enterprise-api/community-notes/delete-a-community-note.md): Reference documentation for the endpoint and related functionality. +- [Evaluate A Community Note](https://docs.x.com/enterprise-api/community-notes/evaluate-a-community-note.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/enterprise-api/community-notes/introduction.md): The Community Notes Endpoints in the X API v2 allow developers to search for and propose Community Notes on X programm +- [Quickstart](https://docs.x.com/enterprise-api/community-notes/quickstart.md): Create and search Community Notes via the API +- [Search For Community Notes Written](https://docs.x.com/enterprise-api/community-notes/search-for-community-notes-written.md): Reference documentation for the endpoint and related functionality. +- [Search For Posts Eligible For Community Notes](https://docs.x.com/enterprise-api/community-notes/search-for-posts-eligible-for-community-notes.md): Reference documentation for the endpoint and related functionality. + +## Compliance +- [Create Compliance Job](https://docs.x.com/enterprise-api/compliance/create-compliance-job.md): Reference documentation for the endpoint and related functionality. +- [Get Compliance Job By Id](https://docs.x.com/enterprise-api/compliance/get-compliance-job-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Compliance Jobs](https://docs.x.com/enterprise-api/compliance/get-compliance-jobs.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/enterprise-api/compliance/streams/introduction.md): X is committed to our community of developers who build with the X API. As part of this commitment, we aim to make our +- [Integration guide](https://docs.x.com/enterprise-api/compliance/batch-compliance/integrate.md): When using the Batch compliance endpoints, developers can batch upload large amounts of X data and understand what act +- [Batch Compliance](https://docs.x.com/enterprise-api/compliance/batch-compliance/introduction.md): Check compliance status for Posts and users in bulk +- [Quickstart](https://docs.x.com/enterprise-api/compliance/batch-compliance/quickstart.md): Create and run a batch compliance job + +## Connections +- [Get Connection History](https://docs.x.com/enterprise-api/connections/get-connection-history.md): Reference documentation for the endpoint and related functionality. +- [Stream Connections](https://docs.x.com/enterprise-api/connections/introduction.md): View and manage your streaming connections for X API v2 +- [Terminate All Connections](https://docs.x.com/enterprise-api/connections/terminate-all-connections.md): Reference documentation for the endpoint and related functionality. +- [Terminate Connections By Endpoint](https://docs.x.com/enterprise-api/connections/terminate-connections-by-endpoint.md): Reference documentation for the endpoint and related functionality. +- [Terminate Multiple Connections](https://docs.x.com/enterprise-api/connections/terminate-multiple-connections.md): Reference documentation for the endpoint and related functionality. + +## Direct Messages +- [Create Dm Conversation](https://docs.x.com/enterprise-api/direct-messages/create-dm-conversation.md): Reference documentation for the endpoint and related functionality. +- [Create Dm Message By Conversation Id](https://docs.x.com/enterprise-api/direct-messages/create-dm-message-by-conversation-id.md): Reference documentation for the endpoint and related functionality. +- [Create Dm Message By Participant Id](https://docs.x.com/enterprise-api/direct-messages/create-dm-message-by-participant-id.md): Reference documentation for the endpoint and related functionality. +- [Delete Dm Event](https://docs.x.com/enterprise-api/direct-messages/delete-dm-event.md): Reference documentation for the endpoint and related functionality. +- [Download Dm Media](https://docs.x.com/enterprise-api/direct-messages/download-dm-media.md): Reference documentation for the endpoint and related functionality. +- [Get Dm Event By Id](https://docs.x.com/enterprise-api/direct-messages/get-dm-event-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Dm Events For A Dm Conversation 1](https://docs.x.com/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation-1.md): Reference documentation for the endpoint and related functionality. +- [Get Dm Events For A Dm Conversation](https://docs.x.com/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation.md): Reference documentation for the endpoint and related functionality. +- [Get Dm Events](https://docs.x.com/enterprise-api/direct-messages/get-dm-events.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/enterprise-api/direct-messages/blocks/introduction.md): The manage DM blocks endpoints enable you to block or unblock a specified account on behalf of an authenticated user. +- [Integration Guide](https://docs.x.com/enterprise-api/direct-messages/lookup/integrate.md): Key concepts and best practices for integrating DM lookup endpoints +- [Direct Messages Lookup](https://docs.x.com/enterprise-api/direct-messages/lookup/introduction.md): Retrieve Direct Message events and conversations +- [Migration guide](https://docs.x.com/enterprise-api/direct-messages/lookup/migrate.md): 1 and v2 versions of the Direct Messages endpoints provide methods for looking up Direct Message events. +- [Quickstart](https://docs.x.com/enterprise-api/direct-messages/lookup/quickstart.md): Retrieve Direct Message events and conversations +- [Integration Guide](https://docs.x.com/enterprise-api/direct-messages/manage/integrate.md): Key concepts and best practices for sending Direct Messages +- [Manage Direct Messages](https://docs.x.com/enterprise-api/direct-messages/manage/introduction.md): Send and delete Direct Messages +- [Migration guide](https://docs.x.com/enterprise-api/direct-messages/manage/migrate.md): 1 and v2 versions of the Direct Messages endpoints provide methods for creating Direct Message messages. +- [Quickstart](https://docs.x.com/enterprise-api/direct-messages/manage/quickstart.md): Send Direct Messages and create group conversations + +## General +- [Get Openapi Spec](https://docs.x.com/enterprise-api/general/get-openapi-spec.md): Reference documentation for the endpoint and related functionality. + +## Getting Started +- [About the Enterprise API](https://docs.x.com/enterprise-api/getting-started/about-x-api.md): Overview of Enterprise API capabilities, exclusive endpoints, and dedicated support +- [Getting Enterprise Access](https://docs.x.com/enterprise-api/getting-started/getting-access.md): Apply for Enterprise API access and get onboarded +- [Important Resources](https://docs.x.com/enterprise-api/getting-started/important-resources.md): Key documentation, tools, and community resources +- [Make Your First Request](https://docs.x.com/enterprise-api/getting-started/make-your-first-request.md): Get up and running with the X API in minutes +- [Enterprise Pricing](https://docs.x.com/enterprise-api/getting-started/pricing.md): Custom Enterprise pricing for the X API + +## Lists +- [Add List Member](https://docs.x.com/enterprise-api/lists/add-list-member.md): Reference documentation for the endpoint and related functionality. +- [Create List](https://docs.x.com/enterprise-api/lists/create-list.md): Reference documentation for the endpoint and related functionality. +- [Delete List](https://docs.x.com/enterprise-api/lists/delete-list.md): Reference documentation for the endpoint and related functionality. +- [Get List By Id](https://docs.x.com/enterprise-api/lists/get-list-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get List Followers](https://docs.x.com/enterprise-api/lists/get-list-followers.md): Reference documentation for the endpoint and related functionality. +- [Get List Members](https://docs.x.com/enterprise-api/lists/get-list-members.md): Reference documentation for the endpoint and related functionality. +- [Get List Posts](https://docs.x.com/enterprise-api/lists/get-list-posts.md): Reference documentation for the endpoint and related functionality. +- [Remove List Member](https://docs.x.com/enterprise-api/lists/remove-list-member.md): Reference documentation for the endpoint and related functionality. +- [Update List](https://docs.x.com/enterprise-api/lists/update-list.md): Reference documentation for the endpoint and related functionality. +- [Integration guide](https://docs.x.com/enterprise-api/lists/list-tweets/integrate.md): This page covers tools and key concepts for integrating the List Posts lookup endpoint. +- [List Posts](https://docs.x.com/enterprise-api/lists/list-tweets/introduction.md): Retrieve Posts from a List's timeline +- [Quickstart](https://docs.x.com/enterprise-api/lists/list-tweets/quickstart.md): Get Posts from a List timeline +- [Overview](https://docs.x.com/enterprise-api/lists/list-tweets/migrate/overview.md): The v2 List Posts lookup endpoint will replace the standard v1. 1 [GET lists/statuses](https://developer. +- [v1 to v2](https://docs.x.com/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET lists/statuses](https://developer. +- [Integration guide](https://docs.x.com/enterprise-api/lists/list-members/integrate.md): This page covers tools and key concepts for integrating the List members endpoints. +- [List Members](https://docs.x.com/enterprise-api/lists/list-members/introduction.md): View, add, and remove members from Lists +- [List Members Lookup](https://docs.x.com/enterprise-api/lists/list-members/quickstart/list-members-lookup.md): Get members of a List +- [Manage List Members](https://docs.x.com/enterprise-api/lists/list-members/quickstart/manage-list-members.md): Add and remove members from a List +- [List Members Overview](https://docs.x.com/enterprise-api/lists/list-members/quickstart/overview.md): Get started with List members endpoints +- [List members lookup](https://docs.x.com/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET lists/members](https://developer. +- [Manage list members](https://docs.x.com/enterprise-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST lists/members/create](https://developer. +- [Overview](https://docs.x.com/enterprise-api/lists/list-members/migrate/overview.md): The v2 List members endpoint group will replace the standard v1. 1 [GET lists/members](https://developer. +- [Integration guide](https://docs.x.com/enterprise-api/lists/pinned-lists/integrate.md): This page covers tools and key concepts for integrating the pinned Lists endpoints. +- [Pinned Lists](https://docs.x.com/enterprise-api/lists/pinned-lists/introduction.md): View and manage pinned Lists +- [Manage Pinned Lists](https://docs.x.com/enterprise-api/lists/pinned-lists/quickstart/manage-pinned-lists.md): Pin and unpin Lists +- [Pinned Lists Overview](https://docs.x.com/enterprise-api/lists/pinned-lists/quickstart/overview.md): Get started with pinned List endpoints +- [Pinned Lists Lookup](https://docs.x.com/enterprise-api/lists/pinned-lists/quickstart/pinned-list-lookup.md): Get a user's pinned Lists +- [Integration guide](https://docs.x.com/enterprise-api/lists/manage-lists/integrate.md): This page covers tools and key concepts for integrating the Lists endpoints. +- [Manage Lists](https://docs.x.com/enterprise-api/lists/manage-lists/introduction.md): Create, update, and delete Lists +- [Quickstart](https://docs.x.com/enterprise-api/lists/manage-lists/quickstart.md): Create, update, and delete Lists +- [Overview](https://docs.x.com/enterprise-api/lists/manage-lists/migrate/overview.md): The v2 manage Lists endpoints will eventually replace [POST lists/create](https://developer. +- [v1 to v2](https://docs.x.com/enterprise-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST lists/create](https://developer. +- [Integration Guide](https://docs.x.com/enterprise-api/lists/list-lookup/integrate.md): Key concepts and best practices for integrating List lookup +- [List Lookup](https://docs.x.com/enterprise-api/lists/list-lookup/introduction.md): Retrieve List details by ID or get Lists owned by a user +- [Quickstart](https://docs.x.com/enterprise-api/lists/list-lookup/quickstart.md): Look up Lists by ID or owner +- [Overview](https://docs.x.com/enterprise-api/lists/list-lookup/migrate/overview.md): The v2 List lookup endpoint group will replace the standard v1. 1 [GET lists/show](https://developer. +- [v1 to v2](https://docs.x.com/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET lists/show](https://developer. + +## Marketplace +- [Get Marketplace Handle Availability](https://docs.x.com/enterprise-api/marketplace/get-marketplace-handle-availability.md): Reference documentation for the endpoint and related functionality. + +## Media +- [Append Media Upload](https://docs.x.com/enterprise-api/media/append-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Create Media Metadata](https://docs.x.com/enterprise-api/media/create-media-metadata.md): Reference documentation for the endpoint and related functionality. +- [Create Media Subtitles](https://docs.x.com/enterprise-api/media/create-media-subtitles.md): Reference documentation for the endpoint and related functionality. +- [Delete Media Subtitles](https://docs.x.com/enterprise-api/media/delete-media-subtitles.md): Reference documentation for the endpoint and related functionality. +- [Finalize Media Upload](https://docs.x.com/enterprise-api/media/finalize-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Get Media Analytics](https://docs.x.com/enterprise-api/media/get-media-analytics.md): Reference documentation for the endpoint and related functionality. +- [Get Media By Media Key](https://docs.x.com/enterprise-api/media/get-media-by-media-key.md): Reference documentation for the endpoint and related functionality. +- [Get Media By Media Keys](https://docs.x.com/enterprise-api/media/get-media-by-media-keys.md): Reference documentation for the endpoint and related functionality. +- [Get Media Upload Status](https://docs.x.com/enterprise-api/media/get-media-upload-status.md): Reference documentation for the endpoint and related functionality. +- [Initialize Media Upload](https://docs.x.com/enterprise-api/media/initialize-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/enterprise-api/media/introduction.md): A media object represents a single photo, video or animated GIF. Media objects are used by many endpoints within the X +- [Upload Media](https://docs.x.com/enterprise-api/media/upload-media.md): Reference documentation for the endpoint and related functionality. +- [Best practices](https://docs.x.com/enterprise-api/media/quickstart/best-practices.md): There are a few important concepts to understand when using the [`POST /2/media/upload`](/x-api/media/media-upload) en +- [Chunked Media Upload](https://docs.x.com/enterprise-api/media/quickstart/media-upload-chunked.md): Upload videos and large media files using chunked upload + +## News +- [Get News Stories By Id](https://docs.x.com/enterprise-api/news/get-news-stories-by-id.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/enterprise-api/news/introduction.md): The news lookup endpoint allows developers to get news and headlines breaking on X. This endpoint supports app-auth an +- [Search News](https://docs.x.com/enterprise-api/news/search-news.md): Reference documentation for the endpoint and related functionality. + +## Posts +- [Create Or Edit Post](https://docs.x.com/enterprise-api/posts/create-or-edit-post.md): Reference documentation for the endpoint and related functionality. +- [Create Post](https://docs.x.com/enterprise-api/posts/create-post.md): Reference documentation for the endpoint and related functionality. +- [Delete Post](https://docs.x.com/enterprise-api/posts/delete-post.md): Reference documentation for the endpoint and related functionality. +- [Get 28 Hour Post Insights](https://docs.x.com/enterprise-api/posts/get-28-hour-post-insights.md): Reference documentation for the endpoint and related functionality. +- [Get Count Of All Posts](https://docs.x.com/enterprise-api/posts/get-count-of-all-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Count Of Recent Posts](https://docs.x.com/enterprise-api/posts/get-count-of-recent-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Historical Post Insights](https://docs.x.com/enterprise-api/posts/get-historical-post-insights.md): Reference documentation for the endpoint and related functionality. +- [Get Liking Users](https://docs.x.com/enterprise-api/posts/get-liking-users.md): Reference documentation for the endpoint and related functionality. +- [Get Post Analytics](https://docs.x.com/enterprise-api/posts/get-post-analytics.md): Reference documentation for the endpoint and related functionality. +- [Get Post By Id](https://docs.x.com/enterprise-api/posts/get-post-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Posts By Ids](https://docs.x.com/enterprise-api/posts/get-posts-by-ids.md): Reference documentation for the endpoint and related functionality. +- [Get Quoted Posts](https://docs.x.com/enterprise-api/posts/get-quoted-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Reposted By](https://docs.x.com/enterprise-api/posts/get-reposted-by.md): Reference documentation for the endpoint and related functionality. +- [Get Reposts](https://docs.x.com/enterprise-api/posts/get-reposts.md): Reference documentation for the endpoint and related functionality. +- [Hide Reply](https://docs.x.com/enterprise-api/posts/hide-reply.md): Reference documentation for the endpoint and related functionality. +- [Search All Posts](https://docs.x.com/enterprise-api/posts/search-all-posts.md): Reference documentation for the endpoint and related functionality. +- [Search Recent Posts](https://docs.x.com/enterprise-api/posts/search-recent-posts.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/enterprise-api/posts/volume-streams/introduction.md): * 1% sampled stream. * 10% sampled stream. +- [Integration guide](https://docs.x.com/enterprise-api/posts/retweets/integrate.md): This page covers tools and key concepts for integrating the Retweet endpoints. +- [Retweets](https://docs.x.com/enterprise-api/posts/retweets/introduction.md): Retweet and undo retweets, and retrieve retweet information +- [Manage Retweets](https://docs.x.com/enterprise-api/posts/retweets/quickstart/manage-retweets.md): Retweet and undo Retweets using the X API +- [Retweets Lookup](https://docs.x.com/enterprise-api/posts/retweets/quickstart/retweets-lookup.md): Get users who Retweeted a Post +- [Retweets of Me](https://docs.x.com/enterprise-api/posts/retweets/quickstart/retweets-of-me.md): Get your Posts that have been Retweeted +- [Manage Retweets](https://docs.x.com/enterprise-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST statuses/retweet/:id](https://developer. +- [Overview](https://docs.x.com/enterprise-api/posts/retweets/migrate/overview.md): **Retweets lookup** The v2 Retweets lookup endpoint will replace the standard [v1. 1 GET statuses/retweets/:id](https: +- [Retweets lookup](https://docs.x.com/enterprise-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. +- [Likes](https://docs.x.com/enterprise-api/posts/likes/introduction.md): Like and unlike Posts, and retrieve like information +- [Likes Lookup](https://docs.x.com/enterprise-api/posts/likes/quickstart/likes-lookup.md): Get users who liked a Post and Posts liked by a user +- [Manage Likes](https://docs.x.com/enterprise-api/posts/likes/quickstart/manage-likes.md): Like and unlike Posts using the X API +- [Likes lookup](https://docs.x.com/enterprise-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET favorites/list](https://developer. +- [Manage Likes](https://docs.x.com/enterprise-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST favorites/create](https://developer. +- [Overview](https://docs.x.com/enterprise-api/posts/likes/migrate/overview.md): These guides will focus on the following areas: * **API request parameters** - The X API v2 endpoint introduces a new +- [Apps](https://docs.x.com/enterprise-api/posts/hide-replies/apps.md): Here's a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their +- [Hide Replies](https://docs.x.com/enterprise-api/posts/hide-replies/introduction.md): Hide and unhide replies to Posts you authored +- [Migration guide](https://docs.x.com/enterprise-api/posts/hide-replies/migrate.md): The v2 hide replies endpoint is replacing the Labs hide replies endpoint. If you have code, apps, or tools that use th +- [Quickstart](https://docs.x.com/enterprise-api/posts/hide-replies/quickstart.md): Hide and unhide replies to your Posts +- [Manage replies by topic](https://docs.x.com/enterprise-api/posts/hide-replies/integrate/manage-replies-by-topic.md): Through the hide replies endpoint, you can build integrations to help people and brands keep their conversation on top +- [Manage replies by topic](https://docs.x.com/enterprise-api/posts/hide-replies/integrate/manage-replies-in-realtime.md): With the hide replies endpoint, you can build a workflow to helps your users hide replies that have a very high-probab +- [Integration Guide](https://docs.x.com/enterprise-api/posts/lookup/integrate.md): Key concepts and best practices for integrating Post lookup +- [Post Lookup](https://docs.x.com/enterprise-api/posts/lookup/introduction.md): Retrieve Posts by ID to get details, verify availability, and examine edit history +- [Quickstart](https://docs.x.com/enterprise-api/posts/lookup/quickstart.md): Make your first Post lookup request in minutes +- [Overview](https://docs.x.com/enterprise-api/posts/lookup/migrate/overview.md): The v2 Posts lookup endpoints replace the standard v1. 1 [GET statuses/lookup](https://developer. +- [v1 to v2](https://docs.x.com/enterprise-api/posts/lookup/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 GET statuses/show and GET statuses/lookup, this guide will help you u +- [Integration Guide](https://docs.x.com/enterprise-api/posts/timelines/integrate.md): Key concepts and best practices for integrating Timelines endpoints +- [Timelines](https://docs.x.com/enterprise-api/posts/timelines/introduction.md): Retrieve Posts from user timelines and home feeds +- [Home Timeline Quickstart](https://docs.x.com/enterprise-api/posts/timelines/quickstart/reverse-chron-quickstart.md): Get a user's home timeline in reverse chronological order +- [User Mentions Timeline](https://docs.x.com/enterprise-api/posts/timelines/quickstart/user-mention-quickstart.md): Get Posts that mention a specific user +- [Overview](https://docs.x.com/enterprise-api/posts/timelines/migrate/overview.md): The v2 reverse chronological timeline, user Posts timeline, and user mention timeline endpoints replace the [v1. 1 sta +- [v1 to v2](https://docs.x.com/enterprise-api/posts/timelines/migrate/standard-to-twitter-api-v2.md): If you have been working with the v1. 1 timelines endpoints (statuses/user\_timeline and statuses/mentions\_timeline), +- [Search Posts](https://docs.x.com/enterprise-api/posts/search/introduction.md): Search for Posts by keyword, hashtag, user, and more with powerful query operators +- [Build a query](https://docs.x.com/enterprise-api/posts/search/integrate/build-a-query.md): Learn how to build search queries using operators +- [Search Operators](https://docs.x.com/enterprise-api/posts/search/integrate/operators.md): Complete list of operators for Search queries +- [Integration Guide](https://docs.x.com/enterprise-api/posts/search/integrate/overview.md): Key concepts and best practices for integrating Search Posts +- [Pagination](https://docs.x.com/enterprise-api/posts/search/integrate/paginate.md): Search queries typically match on more Posts than can be returned in a single API response. When that happens, the dat +- [Full-Archive Search Quickstart](https://docs.x.com/enterprise-api/posts/search/quickstart/full-archive-search.md): Search the complete Post archive back to 2006 +- [Recent Search Quickstart](https://docs.x.com/enterprise-api/posts/search/quickstart/recent-search.md): Make your first recent search request in minutes +- [v1 to v2 (Enterprise)](https://docs.x.com/enterprise-api/posts/search/migrate/enterprise-to-twitter-api-v2.md): **Similarities** * Pagination * Timezone * Support for Post edit history and metadata. **Differences** * Endpoint URLs +- [Overview](https://docs.x.com/enterprise-api/posts/search/migrate/overview.md): The v2 Search Tweets endpoint will eventually replace the [standard v1. 1 search/posts](/x-api/posts/search/introducti +- [v1 to v2](https://docs.x.com/enterprise-api/posts/search/migrate/standard-to-twitter-api-v2.md): If you have been working with the v1. 1 [search/posts](/x-api/posts/search/introduction), the goal of this guide is to +- [Integration guide](https://docs.x.com/enterprise-api/posts/bookmarks/integrate.md): This page contains information on several tools and critical concepts that you should know as you integrate the manage +- [Bookmarks](https://docs.x.com/enterprise-api/posts/bookmarks/introduction.md): Save and manage bookmarked Posts for the authenticated user +- [Bookmarks Lookup](https://docs.x.com/enterprise-api/posts/bookmarks/quickstart/bookmarks-lookup.md): Retrieve your bookmarked Posts +- [Manage Bookmarks](https://docs.x.com/enterprise-api/posts/bookmarks/quickstart/manage-bookmarks.md): Add and remove bookmarks using the X API +- [Quote Posts](https://docs.x.com/enterprise-api/posts/quote-tweets/introduction.md): Retrieve Quote Posts for a specific Post +- [Quickstart](https://docs.x.com/enterprise-api/posts/quote-tweets/quickstart.md): Retrieve Quote Posts for a specific Post +- [Filtered Stream](https://docs.x.com/enterprise-api/posts/filtered-stream/introduction.md): Stream near real-time Posts matching your filter rules +- [Quickstart](https://docs.x.com/enterprise-api/posts/filtered-stream/quickstart.md): Connect to the filtered stream and receive near real-time Posts +- [Build a rule](https://docs.x.com/enterprise-api/posts/filtered-stream/integrate/build-a-rule.md): Learn how to build filtered stream rules using operators +- [Matching Posts to Rules](https://docs.x.com/enterprise-api/posts/filtered-stream/integrate/matching-returned-tweets.md): The filtered stream endpoint gives you the ability to have multiple rules in place through a single connection. Before +- [Filtered Stream Operators](https://docs.x.com/enterprise-api/posts/filtered-stream/integrate/operators.md): Complete list of operators for Filtered Stream rules +- [Overview](https://docs.x.com/enterprise-api/posts/filtered-stream/migrate/overview.md): The v2 filtered stream endpoints group is replacing the [standard v1. 1 statuses/filter](https://developer. +- [v1 to v2 (Enterprise)](https://docs.x.com/enterprise-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.md): Use this migration guide to understand the similarities and differences between [PowerTrack API](/x-api/enterprise-gni +- [v1 to v2](https://docs.x.com/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.md): If you have been working with the v1. 1 [statuses/filter](https://developer. +- [Post Counts](https://docs.x.com/enterprise-api/posts/counts/introduction.md): Get Post volume data for queries without retrieving the Posts themselves +- [Build a query](https://docs.x.com/enterprise-api/posts/counts/integrate/build-a-query.md): **Query limitations! ** Your queries will be limited depending on which [access level](/x-api/getting-started/about-x- +- [Overview](https://docs.x.com/enterprise-api/posts/counts/integrate/overview.md): This page covers tools and key concepts for integrating the Post counts endpoints. +- [Full-Archive Post Counts](https://docs.x.com/enterprise-api/posts/counts/quickstart/full-archive-tweet-counts.md): Get historical Post volume back to 2006 +- [Recent Post Counts](https://docs.x.com/enterprise-api/posts/counts/quickstart/recent-tweet-counts.md): Get Post volume for the last 7 days +- [v1 to v2 (Enterprise)](https://docs.x.com/enterprise-api/posts/counts/migrate/enterprise-to-twitter-api-v2.md): **Similarities** * Granularity * Pagination * Timezone **Differences** * Endpoint URLs * App and Project requirement * +- [Overview](https://docs.x.com/enterprise-api/posts/counts/migrate/overview.md): The v2 Post counts endpoint will eventually replace the [enterprise Search API’s counts endpoint](/x-api/enterprise-gn +- [Integration guide](https://docs.x.com/enterprise-api/posts/manage-tweets/integrate.md): This page covers tools and key concepts for integrating the manage Posts endpoints into your system. +- [Manage Posts](https://docs.x.com/enterprise-api/posts/manage-tweets/introduction.md): Create and delete Posts on behalf of authenticated users +- [Quickstart](https://docs.x.com/enterprise-api/posts/manage-tweets/quickstart.md): Create and delete Posts using the X API +- [Overview](https://docs.x.com/enterprise-api/posts/manage-tweets/migrate/overview.md): The v2 manage Posts endpoints will replace the standard v1. 1 [POST statuses/update](https://developer. +- [v1 to v2](https://docs.x.com/enterprise-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST statuses/update](https://developer. + +## Powerstream +- [Handling disconnections](https://docs.x.com/enterprise-api/powerstream/handling-disconnections.md): This page covers Powerstream-specific disconnection handling. For comprehensive guidance on handling disconnections ac +- [Introduction](https://docs.x.com/enterprise-api/powerstream/introduction.md): Powerstream is our **lowest-latency streaming API** for accessing public X data in real-time. Unlike other streaming e +- [Powerstream Operators](https://docs.x.com/enterprise-api/powerstream/operators.md): Complete list of operators for Powerstream filtering rules +- [Recovery and redundancy](https://docs.x.com/enterprise-api/powerstream/recovery-and-redundancy.md): This page covers Powerstream-specific recovery and redundancy features. For comprehensive guidance on recovery and red + +## Spaces +- [Get Space By Id](https://docs.x.com/enterprise-api/spaces/get-space-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Space Posts](https://docs.x.com/enterprise-api/spaces/get-space-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Space Ticket Buyers](https://docs.x.com/enterprise-api/spaces/get-space-ticket-buyers.md): Reference documentation for the endpoint and related functionality. +- [Get Spaces By Creator Ids](https://docs.x.com/enterprise-api/spaces/get-spaces-by-creator-ids.md): Reference documentation for the endpoint and related functionality. +- [Get Spaces By Ids](https://docs.x.com/enterprise-api/spaces/get-spaces-by-ids.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/enterprise-api/spaces/introduction.md): The following page describes the Spaces endpoints included in the X API. To learn more about Spaces in general, please +- [Search Spaces](https://docs.x.com/enterprise-api/spaces/search-spaces.md): Reference documentation for the endpoint and related functionality. +- [Spaces Lookup](https://docs.x.com/enterprise-api/spaces/lookup/introduction.md): Retrieve Space details by ID or find Spaces by their creators +- [Quickstart](https://docs.x.com/enterprise-api/spaces/lookup/quickstart.md): Retrieve Space details by ID or creator +- [Spaces Search](https://docs.x.com/enterprise-api/spaces/search/introduction.md): Search for live or scheduled Spaces by keyword +- [Quickstart](https://docs.x.com/enterprise-api/spaces/search/quickstart.md): Search for Spaces by keyword + +## Stream +- [Get Stream Rule Counts](https://docs.x.com/enterprise-api/stream/get-stream-rule-counts.md): Reference documentation for the endpoint and related functionality. +- [Get Stream Rules](https://docs.x.com/enterprise-api/stream/get-stream-rules.md): Reference documentation for the endpoint and related functionality. +- [Likes Streams](https://docs.x.com/enterprise-api/stream/likes-streams-introduction.md): Stream real-time like events from across X +- [Stream 10 Sampled Posts](https://docs.x.com/enterprise-api/stream/stream-10-sampled-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream All Likes](https://docs.x.com/enterprise-api/stream/stream-all-likes.md): Reference documentation for the endpoint and related functionality. +- [Stream All Posts](https://docs.x.com/enterprise-api/stream/stream-all-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream English Posts](https://docs.x.com/enterprise-api/stream/stream-english-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Filtered Posts](https://docs.x.com/enterprise-api/stream/stream-filtered-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Japanese Posts](https://docs.x.com/enterprise-api/stream/stream-japanese-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Korean Posts](https://docs.x.com/enterprise-api/stream/stream-korean-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Likes Compliance Data](https://docs.x.com/enterprise-api/stream/stream-likes-compliance-data.md): Reference documentation for the endpoint and related functionality. +- [Stream Portuguese Posts](https://docs.x.com/enterprise-api/stream/stream-portuguese-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Post Labels](https://docs.x.com/enterprise-api/stream/stream-post-labels.md): Reference documentation for the endpoint and related functionality. +- [Stream Posts Compliance Data](https://docs.x.com/enterprise-api/stream/stream-posts-compliance-data.md): Reference documentation for the endpoint and related functionality. +- [Stream Sampled Likes](https://docs.x.com/enterprise-api/stream/stream-sampled-likes.md): Reference documentation for the endpoint and related functionality. +- [Stream Sampled Posts](https://docs.x.com/enterprise-api/stream/stream-sampled-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Users Compliance Data](https://docs.x.com/enterprise-api/stream/stream-users-compliance-data.md): Reference documentation for the endpoint and related functionality. +- [Update Stream Rules](https://docs.x.com/enterprise-api/stream/update-stream-rules.md): Reference documentation for the endpoint and related functionality. + +## Trends +- [Get Ai Trends By Id](https://docs.x.com/enterprise-api/trends/get-ai-trends-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Personalized Trends](https://docs.x.com/enterprise-api/trends/get-personalized-trends.md): Reference documentation for the endpoint and related functionality. +- [Get Trends By Woeid](https://docs.x.com/enterprise-api/trends/get-trends-by-woeid.md): Reference documentation for the endpoint and related functionality. +- [Trends by WOEID](https://docs.x.com/enterprise-api/trends/trends-by-woeid/introduction.md): Get trending topics for a specific geographic location +- [Personalized Trends](https://docs.x.com/enterprise-api/trends/personalized-trends/introduction.md): Get trending topics personalized for the authenticated user + +## Usage +- [Get Usage](https://docs.x.com/enterprise-api/usage/get-usage.md): Reference documentation for the endpoint and related functionality. +- [Usage](https://docs.x.com/enterprise-api/usage/introduction.md): Monitor your API usage and track Post consumption + +## Users +- [Block Dms](https://docs.x.com/enterprise-api/users/block-dms.md): Reference documentation for the endpoint and related functionality. +- [Create Bookmark](https://docs.x.com/enterprise-api/users/create-bookmark.md): Reference documentation for the endpoint and related functionality. +- [Delete Bookmark](https://docs.x.com/enterprise-api/users/delete-bookmark.md): Reference documentation for the endpoint and related functionality. +- [Follow List](https://docs.x.com/enterprise-api/users/follow-list.md): Reference documentation for the endpoint and related functionality. +- [Follow User](https://docs.x.com/enterprise-api/users/follow-user.md): Reference documentation for the endpoint and related functionality. +- [Get Affiliates](https://docs.x.com/enterprise-api/users/get-affiliates.md): Reference documentation for the endpoint and related functionality. +- [Get Blocking](https://docs.x.com/enterprise-api/users/get-blocking.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmark Folders](https://docs.x.com/enterprise-api/users/get-bookmark-folders.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmarks By Folder Id](https://docs.x.com/enterprise-api/users/get-bookmarks-by-folder-id.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmarks](https://docs.x.com/enterprise-api/users/get-bookmarks.md): Reference documentation for the endpoint and related functionality. +- [Get Followed Lists](https://docs.x.com/enterprise-api/users/get-followed-lists.md): Reference documentation for the endpoint and related functionality. +- [Get Followers](https://docs.x.com/enterprise-api/users/get-followers.md): Reference documentation for the endpoint and related functionality. +- [Get Following](https://docs.x.com/enterprise-api/users/get-following.md): Reference documentation for the endpoint and related functionality. +- [Get Liked Posts](https://docs.x.com/enterprise-api/users/get-liked-posts.md): Reference documentation for the endpoint and related functionality. +- [Get List Memberships](https://docs.x.com/enterprise-api/users/get-list-memberships.md): Reference documentation for the endpoint and related functionality. +- [Get Mentions](https://docs.x.com/enterprise-api/users/get-mentions.md): Reference documentation for the endpoint and related functionality. +- [Get Muting](https://docs.x.com/enterprise-api/users/get-muting.md): Reference documentation for the endpoint and related functionality. +- [Get My User](https://docs.x.com/enterprise-api/users/get-my-user.md): Reference documentation for the endpoint and related functionality. +- [Get Owned Lists](https://docs.x.com/enterprise-api/users/get-owned-lists.md): Reference documentation for the endpoint and related functionality. +- [Get Pinned Lists](https://docs.x.com/enterprise-api/users/get-pinned-lists.md): Reference documentation for the endpoint and related functionality. +- [Get Posts](https://docs.x.com/enterprise-api/users/get-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Public Keys For Multiple Users](https://docs.x.com/enterprise-api/users/get-public-keys-for-multiple-users.md): Reference documentation for the endpoint and related functionality. +- [Get Reposts Of Me](https://docs.x.com/enterprise-api/users/get-reposts-of-me.md): Reference documentation for the endpoint and related functionality. +- [Get Timeline](https://docs.x.com/enterprise-api/users/get-timeline.md): Reference documentation for the endpoint and related functionality. +- [Get User By Id](https://docs.x.com/enterprise-api/users/get-user-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get User By Username](https://docs.x.com/enterprise-api/users/get-user-by-username.md): Reference documentation for the endpoint and related functionality. +- [Get User Public Keys](https://docs.x.com/enterprise-api/users/get-user-public-keys.md): Reference documentation for the endpoint and related functionality. +- [Get Users By Ids](https://docs.x.com/enterprise-api/users/get-users-by-ids.md): Reference documentation for the endpoint and related functionality. +- [Get Users By Usernames](https://docs.x.com/enterprise-api/users/get-users-by-usernames.md): Reference documentation for the endpoint and related functionality. +- [Like Post](https://docs.x.com/enterprise-api/users/like-post.md): Reference documentation for the endpoint and related functionality. +- [Mute User](https://docs.x.com/enterprise-api/users/mute-user.md): Reference documentation for the endpoint and related functionality. +- [Pin List](https://docs.x.com/enterprise-api/users/pin-list.md): Reference documentation for the endpoint and related functionality. +- [Repost Post](https://docs.x.com/enterprise-api/users/repost-post.md): Reference documentation for the endpoint and related functionality. +- [Search Users](https://docs.x.com/enterprise-api/users/search-users.md): Reference documentation for the endpoint and related functionality. +- [Unblock Dms](https://docs.x.com/enterprise-api/users/unblock-dms.md): Reference documentation for the endpoint and related functionality. +- [Unfollow List](https://docs.x.com/enterprise-api/users/unfollow-list.md): Reference documentation for the endpoint and related functionality. +- [Unfollow User](https://docs.x.com/enterprise-api/users/unfollow-user.md): Reference documentation for the endpoint and related functionality. +- [Unlike Post](https://docs.x.com/enterprise-api/users/unlike-post.md): Reference documentation for the endpoint and related functionality. +- [Unmute User](https://docs.x.com/enterprise-api/users/unmute-user.md): Reference documentation for the endpoint and related functionality. +- [Unpin List](https://docs.x.com/enterprise-api/users/unpin-list.md): Reference documentation for the endpoint and related functionality. +- [Unrepost Post](https://docs.x.com/enterprise-api/users/unrepost-post.md): Reference documentation for the endpoint and related functionality. +- [Integration Guide](https://docs.x.com/enterprise-api/users/blocks/integrate.md): Key concepts and best practices for integrating blocks endpoints +- [Blocks](https://docs.x.com/enterprise-api/users/blocks/introduction.md): Block and unblock users, and retrieve blocked user lists +- [Migration guide](https://docs.x.com/enterprise-api/users/blocks/migrate.md): If you have been working with the standard v1. 1 [GET blocks/ids](https://developer. +- [Quickstart](https://docs.x.com/enterprise-api/users/blocks/quickstart.md): Block and unblock users, and retrieve your block list +- [Integration Guide](https://docs.x.com/enterprise-api/users/mutes/integrate.md): Key concepts and best practices for integrating mutes endpoints +- [Mutes](https://docs.x.com/enterprise-api/users/mutes/introduction.md): Mute and unmute users, and retrieve muted user lists +- [Manage Mutes](https://docs.x.com/enterprise-api/users/mutes/quickstart/manage-mutes-quickstart.md): Mute and unmute users using the X API +- [Mutes Lookup](https://docs.x.com/enterprise-api/users/mutes/quickstart/mutes-lookup.md): Get the list of users you have muted +- [Manage mutes](https://docs.x.com/enterprise-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST mutes/users/create](https://developer. +- [Mutes lookup](https://docs.x.com/enterprise-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET mutes/users/ids](https://developer. +- [Overview](https://docs.x.com/enterprise-api/users/mutes/migrate/overview.md): The v2 mutes lookup endpoint will replace the standard [v1. 1 GET mutes/users/ids](https://developer. +- [Integration Guide](https://docs.x.com/enterprise-api/users/lookup/integrate.md): Key concepts and best practices for integrating User lookup +- [User Lookup](https://docs.x.com/enterprise-api/users/lookup/introduction.md): Retrieve user profiles by ID, username, or for the authenticated user +- [Authenticated User Quickstart](https://docs.x.com/enterprise-api/users/lookup/quickstart/authenticated-lookup.md): Get the currently authenticated user's profile +- [User Lookup Quickstart](https://docs.x.com/enterprise-api/users/lookup/quickstart/user-lookup.md): Look up users by ID or username +- [Overview](https://docs.x.com/enterprise-api/users/lookup/migrate/overview.md): The v2 user lookup endpoints will replace the standard v1. 1 [GET users/lookup](https://developer. +- [v1 to v2](https://docs.x.com/enterprise-api/users/lookup/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 GET users/show and GET users/lookup, the goal of this guide is to hel +- [User Search](https://docs.x.com/enterprise-api/users/search/introduction.md): Search for users by keyword +- [Follows](https://docs.x.com/enterprise-api/users/follows/introduction.md): Manage follows and retrieve follower/following information +- [Quickstart](https://docs.x.com/enterprise-api/users/follows/quickstart.md): Get followers and following lists, and manage follows +- [Overview](https://docs.x.com/enterprise-api/users/follows/migrate/overview.md): The v2 follows lookup endpoints will replace the standard v1. 1 [followers/ids](https://developer. +- [v1 to v2](https://docs.x.com/enterprise-api/users/follows/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST friendships/create](https://developer. + +## Webhooks +- [Create Replay Job For Webhook](https://docs.x.com/enterprise-api/webhooks/create-replay-job-for-webhook.md): Reference documentation for the endpoint and related functionality. +- [Create Stream Link](https://docs.x.com/enterprise-api/webhooks/create-stream-link.md): Reference documentation for the endpoint and related functionality. +- [Create Webhook](https://docs.x.com/enterprise-api/webhooks/create-webhook.md): Reference documentation for the endpoint and related functionality. +- [Delete Stream Link](https://docs.x.com/enterprise-api/webhooks/delete-stream-link.md): Reference documentation for the endpoint and related functionality. +- [Delete Webhook](https://docs.x.com/enterprise-api/webhooks/delete-webhook.md): Reference documentation for the endpoint and related functionality. +- [Get Stream Links](https://docs.x.com/enterprise-api/webhooks/get-stream-links.md): Reference documentation for the endpoint and related functionality. +- [Get Webhook](https://docs.x.com/enterprise-api/webhooks/get-webhook.md): Reference documentation for the endpoint and related functionality. +- [V2 Webhooks API](https://docs.x.com/enterprise-api/webhooks/introduction.md): Receive real-time event notifications from X via webhook-based JSON messages +- [Quickstart](https://docs.x.com/enterprise-api/webhooks/quickstart.md): Set up your webhook consumer app, implement CRC validation, and start receiving events +- [Validate Webhook](https://docs.x.com/enterprise-api/webhooks/validate-webhook.md): Reference documentation for the endpoint and related functionality. +- [Filtered Stream Webhooks API](https://docs.x.com/enterprise-api/webhooks/stream/introduction.md): The filtered stream endpoint group enables developers to filter a stream of public Posts. This endpoint group’s functi +- [Quickstart](https://docs.x.com/enterprise-api/webhooks/stream/quickstart.md): The v2 filtered stream webhooks API is similar to the [v2 filtered stream endpoint](/x-api/posts/filtered-stream/intro + +## Full Documentation +- [llms-full.txt](https://docs.x.com/llms-full.txt) \ No newline at end of file diff --git a/enterprise-api/marketplace/get-marketplace-handle-availability.mdx b/enterprise-api/marketplace/get-marketplace-handle-availability.mdx index 618c8e1e7..40728fe0c 100644 --- a/enterprise-api/marketplace/get-marketplace-handle-availability.mdx +++ b/enterprise-api/marketplace/get-marketplace-handle-availability.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/marketplace/handles/{handle}/availability ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/append-media-upload.mdx b/enterprise-api/media/append-media-upload.mdx index 42dcb1156..22746b60a 100644 --- a/enterprise-api/media/append-media-upload.mdx +++ b/enterprise-api/media/append-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/upload/{id}/append ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/create-media-metadata.mdx b/enterprise-api/media/create-media-metadata.mdx index f8b4bdcb9..b3e829bb2 100644 --- a/enterprise-api/media/create-media-metadata.mdx +++ b/enterprise-api/media/create-media-metadata.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/metadata ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/create-media-subtitles.mdx b/enterprise-api/media/create-media-subtitles.mdx index dbb9f3f21..7903ab533 100644 --- a/enterprise-api/media/create-media-subtitles.mdx +++ b/enterprise-api/media/create-media-subtitles.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/subtitles ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/delete-media-subtitles.mdx b/enterprise-api/media/delete-media-subtitles.mdx index 4a616660b..68ed298d3 100644 --- a/enterprise-api/media/delete-media-subtitles.mdx +++ b/enterprise-api/media/delete-media-subtitles.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/media/subtitles ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/finalize-media-upload.mdx b/enterprise-api/media/finalize-media-upload.mdx index 4f9c0e41a..25fd59532 100644 --- a/enterprise-api/media/finalize-media-upload.mdx +++ b/enterprise-api/media/finalize-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/upload/{id}/finalize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/get-media-analytics.mdx b/enterprise-api/media/get-media-analytics.mdx index fea9da1e0..b9a7ab6a1 100644 --- a/enterprise-api/media/get-media-analytics.mdx +++ b/enterprise-api/media/get-media-analytics.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/media/analytics ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/get-media-by-media-key.mdx b/enterprise-api/media/get-media-by-media-key.mdx index 416c1dc33..4bffbc21a 100644 --- a/enterprise-api/media/get-media-by-media-key.mdx +++ b/enterprise-api/media/get-media-by-media-key.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/media/{media_key} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/get-media-by-media-keys.mdx b/enterprise-api/media/get-media-by-media-keys.mdx index 0e8b121c8..670174ff2 100644 --- a/enterprise-api/media/get-media-by-media-keys.mdx +++ b/enterprise-api/media/get-media-by-media-keys.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/media ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/get-media-upload-status.mdx b/enterprise-api/media/get-media-upload-status.mdx index be28f5a45..97583a916 100644 --- a/enterprise-api/media/get-media-upload-status.mdx +++ b/enterprise-api/media/get-media-upload-status.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/media/upload ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/initialize-media-upload.mdx b/enterprise-api/media/initialize-media-upload.mdx index 150143a2d..39dbb0a4c 100644 --- a/enterprise-api/media/initialize-media-upload.mdx +++ b/enterprise-api/media/initialize-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/upload/initialize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/media/introduction.mdx b/enterprise-api/media/introduction.mdx index 73b6d4bb5..d23954962 100644 --- a/enterprise-api/media/introduction.mdx +++ b/enterprise-api/media/introduction.mdx @@ -2,7 +2,8 @@ title: Introduction sidebarTitle: Introduction keywords: ["media", "media upload", "images", "videos", "GIF", "media API", "upload media", "media objects", "media ID"] ---- + +description: A media object represents a single photo, video or animated GIF. Media objects are used by many endpoints within the X API, and may be included in Posts...--- A media object represents a single photo, video or animated GIF. Media objects are used by many endpoints within the X API, and may be included in Posts, Direct Messages, user profiles, advertising creatives and elsewhere. Each media object may have multiple display or playback variants, with different resolutions or formats. diff --git a/enterprise-api/media/quickstart/best-practices.mdx b/enterprise-api/media/quickstart/best-practices.mdx index b772362ca..2cdbf6feb 100644 --- a/enterprise-api/media/quickstart/best-practices.mdx +++ b/enterprise-api/media/quickstart/best-practices.mdx @@ -2,7 +2,8 @@ title: Best practices sidebarTitle: Best practices keywords: ["media upload best practices", "upload media", "media best practices", "image upload", "video upload", "media upload guide"] ---- + +description: There are a few important concepts to understand when using the [`POST /2/media/upload`](/x-api/media/media-upload) endpoint. Uploading media with OAuth...--- There are a few important concepts to understand when using the [`POST /2/media/upload`](/x-api/media/media-upload) endpoint. Uploading media with OAuth can be a bit tricky, so we’ve outlined some things to keep in mind as well as a working sample of how to use this endpoint here. diff --git a/enterprise-api/media/upload-media.mdx b/enterprise-api/media/upload-media.mdx index e6aa3e6e8..4a6cab1ef 100644 --- a/enterprise-api/media/upload-media.mdx +++ b/enterprise-api/media/upload-media.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/upload ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/migrate/data-format-migration.mdx b/enterprise-api/migrate/data-format-migration.mdx deleted file mode 100644 index 5dbec96c7..000000000 --- a/enterprise-api/migrate/data-format-migration.mdx +++ /dev/null @@ -1,931 +0,0 @@ ---- -title: Data Formation Migration -keywords: ["data format migration", "data migration", "format changes", "data structure migration", "migrate data format"] ---- -import { Button } from '/snippets/button.mdx'; - -## Introduction - -With the launch of the v2 version of the X API, we have adopted a new data response format and method of requesting different objects and fields, which we are simply calling the X API v2 format.  - -In the general differences section, you can learn about some changes that are relevant to standard, and enterprise users. However, we also put together a specific guide for the [standard v1.1 Native format](https://developer.x.com/en/docs/x-api/v1/data-dictionary/overview), the enterprise [Native Enriched format](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-tweet-object), and the enterprise [Activity Streams format](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#activity-object) which helps to map fields and explains which fields and expansions you must use to request the new v2 fields.  - -* [Native format to X API v2 (standard v1.1)](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2)  -* [Native Enriched to X API v2 (enterprise)](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2) -* [Activity Streams to X API v2 (enterprise)](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) - -You may also be interested in our [visual data format migration tool](/x-api/migrate/data-format-migration#visual-data-format-migration-tool) to help you quickly see the differences between the [X API v1.1 data format](https://developer.x.com/en/docs/x-api/v1/data-dictionary/overview) and the [X API v2 format](/x-api/introduction). - -### General differences - -#### Requesting objects and fields - -One of the biggest changes between the pre-v2 endpoints and v2 is that the newer version only returns a few fields by default, whereas standard, premium, and enterprise endpoints deliver most fields by default. The new version uses parameters called [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) to specifically request additional data beyond the defaults, meaning that you can request just the data you need without having to ingest fields that don’t matter to you.  - -Any fields that you request that relate to the primary data object will return in that primary data object along with the default values. However, if you request any expanded objects using the expansions parameter, the secondary objects will return in a new includes object. You can match the expanded objects in the includes object back to the primary object by using the ID field which will return in both. - -For example, if you are using the v2 [Post lookup](/x-api/posts/lookup/introduction) endpoint and you include the expansions=author_id parameter in your request, you will receive the author_id field within the primary Post object, as well as a user object per Post in the includes object, each of which will include the default id field that can be used to match the user object back to the Post object. Here is an example of what this looks like: - -``` -{ - "data": [ - { - "author_id": "2244994945", - "id": "1397568983931392004", - "text": "The Twitter Developer Platform. Ooh la la! https://t.co/iGTdPXBfOv https://t.co/Ze8z8EODdg" - } - ], - "includes": { - "users": [ - { - "id": "2244994945", - "name": "Twitter Dev", - "username": "TwitterDev" - } - ] - } -} -``` - - -#### Updated JSON design - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a **statuses** array, while X API v2 returns a **data** array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as **contributors** and **user.translator_type** are being removed.  -* Instead of using both **favorites** (in Post object) and **favourites** (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.  -   - -#### New v2 fields - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - - -### Migrating from standard v1.1's data format to v2 - -If you haven't already, we recommend that you read through the [data formats migration](/x-api/migrate/data-format-migration) introduction to start. You may also be interested in our [visual data format migration tool](/x-api/migrate/data-format-migration#visual-data-format-migration-tool) to help you quickly see the differences between the [X API v1.1 data format](https://developer.x.com/en/docs/x-api/v1/data-dictionary/overview) and the [X API v2 format](/x-api/fundamentals/data-dictionary). - -The standard v1.1 data format, also known as the native format, is the primary format that delivers with the [standard v1.1](https://developer.x.com/en/docs/twitter-api/v1) endpoints. - -If you are using the premium product, please refer to the [native enriched guide](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2). Enterprise clients might be using native enriched or activity streams, depending on how you are set up within the Gnip console.  - -#### Standard v1.1 vs v2 payload structure - -The following table displays the high-level objects and format that you can expect to receive from v2 compared to the v1.1 format. - -| | **v1.1 structure** | **v2 structure** | -| :--- | :--- | :--- | -| **Default** | \{
~all tweet object fields~,
"entities": \{
"hashtags": \[\],
"symbols": \[\],
"user_mentions": \[\],
"urls": \[\],
"media": \[\]
},
"extended_entities": {},
"user": {},
"place": {},
"retweeted\_status/quoted\_status"
} | \{
"data": \[\{
"id",
"text",

"edit\_history\_tweet_ids"
}\]
} | -| **With defined [field and expansion](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) parameters** | | \{
"data": \[\{
~tweet object fields~,
"entities": \{
"hashtags": \[\],
"cashtags": \[\],
"mentions": \[\],
"urls": \[\],
},
"attachments": \{

"media_keys": \[\],

"poll_ids": \[\]

}
}\],
"includes": \[
"tweets": \[~tweet objects~\],
"users": \[~user objects~\],
"media": \[~media objects~\],
"places": \[~place object~\],

"polls": \[~poll object~\]
\],

"matching_rules": \[\]
} | - - -**Field mapping** - -The following section describes which v1.1 fields map to v2 fields, as well as which v2 parameters are required to receive the new field. -  - -#### Tweet object - -| | | | -| :--- | :--- | :--- | -| **Twitter 1.1 format** | **Twitter v2 format** | **Required v2 parameters** | -| created_at | data.created_at | tweet.fields=created_at | -| id | | N/A id is a string | -| id_str | data.id | default | -| text | data.text | default | -| full_text | | N/A text includes the complete text | -| truncated | | N/A text includes the complete text | -| display\_text\_range | | N/A text includes the complete text | -| edit_history | data.edit\_history\_tweet_ids | default | -| edit_controls | data.edit_controls | tweet.fields=edit_controls | -| editable | data.edit\_controls.is\_edit_eligible | tweet.fields=edit_controls | -| entities | data.entities | tweet.fields=entities | -| entities.user_mentions | data.entities.mentions | tweet.fields=entities | -| entities.symbols | data.entities.cashtags | tweet.fields=entities | -| entities.hashtags | data.entities.hashtags | tweet.fields=entities | -| entities.urls | data.entities.urls | tweet.fields=entities | -| entities.media | includes.media | expansions=attachments.media_keys | -| extended_entities | data.attachments | tweet_fields=attachments | -| in\_reply\_to\_status\_id | | N/A referenced_tweets.id is a string | -| in\_reply\_to\_status\_id_str | data.referenced_tweets.id (if type=replied_to) | expansions=referenced_tweets.id | -| in\_reply\_to\_user\_id | | N/A in\_reply\_to\_user\_id is a string | -| in\_reply\_to\_user\_id_str | data.in\_reply\_to\_user\_id | tweet.fields=in\_reply\_to\_user\_id | -| in\_reply\_to\_screen\_name | includes.users..username | tweet.fields=in\_reply\_to\_user\_id&expansions=entities.mentions.username | -| user | includes.users | expansions=author_id | -| geo | data.geo.place_id | tweet.fields=geo | -| coordinates | data.geo.place_id | expansions=geo.place_id | -| place | data.geo.place_id | expansions=geo.place_id | -| retweeted_status | data.referenced_tweets.id (if type=retweeted) | expansions=referenced_tweets.id | -| is\_quoted\_status | | Not available | -| quoted\_status\_id | | N/A referenced_tweets.id is a string | -| quoted\_status\_id_str | data.referenced_tweets.id (if type=quoted) | expansions=referenced_tweets.id | -| quoted\_status\_permalink | | Not Available | -| quoted_status | data.referenced_tweets (if type=quoted) | expansions=referenced_tweets.id | -| retweet_count | data.public\_metrics.retweet\_count | tweet.fields=public_metrics | -| favorite_count | data.public\_metrics.like\_count | tweet.fields=public_metrics | -| favorited | | Not available | -| retweeted | | Not available | -| possibly_sensitive | data.possibly_sensitive | tweet.fields=possibly_sensitive | -| lang | data.lang | tweet.fields=lang | -| scopes | | Not available | -| withheld | data.withheld | tweet.fields=withheld | - -**Example** - -| | | -| :--- | :--- | -| **Tweet object in 1.1**

Example URI with parameters:

https://api.x.com/1.1/statuses/lookup.json?id=1359554366051504129&tweet_mode=extended | **Tweet object and request with v2**

Example URI with parameters:

https://api.x.com/2/tweets?ids=1359554366051504129&tweet.fields=attachments,author\_id,context\_annotations,conversation\_id,created\_at,entities,geo,id,in\_reply\_to\_user\_id,lang,possibly\_sensitive,public\_metrics,referenced\_tweets,reply\_settings,text,withheld | -| \{
"created_at": "Wed Feb 10 17:26:34 +0000 2021",
"id": 1359554366051504129,
"id_str": "1359554366051504129",
"text": "Go ahead, follow another puppy account. We won’t judge. \\n\\nIntroducing the manage follows endpoints to the new… https:\\/\\/t.co\\/3cBZKZUevF",
"truncated": true,
"entities": \{
"hashtags": \[\],
"symbols": \[\],
"user_mentions": \[\],
"urls": \[\{
"url": "https:\\/\\/t.co\\/3cBZKZUevF",
"expanded_url": "https:\\/\\/twitter.com\\/i\\/web\\/status\\/1359554366051504129",
"display_url": "twitter.com\\/i\\/web\\/status\\/1…",
"indices": \[
111,
134
\]
}\]
},

"in\_reply\_to\_status\_id": null,
"in\_reply\_to\_status\_id_str": null,
"in\_reply\_to\_user\_id": null,
"in\_reply\_to\_user\_id_str": null,
"in\_reply\_to\_screen\_name": null,
"user": \{
...
},
"geo": null,
"coordinates": null,
"place": null,
"contributors": null,
"is\_quote\_status": false,
"retweet_count": 18,
"favorite_count": 98,
"favorited": false,
"retweeted": false,
"possibly_sensitive": false,
"possibly\_sensitive\_appealable": false,
"lang": "en"
} | \{
"data": \[\{
"id": "1359554366051504129",
"text": "Go ahead, follow another puppy account. We won’t judge. \\n\\nIntroducing the manage follows endpoints to the new #TwitterAPI. You can now use the v2 API to follow and unfollow accounts. Learn more https://t.co/mtpd9VIMDa",
"lang": "en",
"conversation_id": "1359554366051504129",
"possibly_sensitive": false,
"reply_settings": "everyone",
"created_at": "2021-02-10T17:26:34.000Z",
"author_id": "2244994945",
"public_metrics": \{
"retweet_count": 18,
"reply_count": 11,
"like_count": 98,
"quote_count": 7
},
"entities": \{
"hashtags": \[\{
"start": 110,
"end": 121,
"tag": "TwitterAPI"
}\],
"urls": \[\{
"start": 194,
"end": 217,
"url": "https://t.co/mtpd9VIMDa",
"expanded_url": "https://devcommunity.x.com/t/introducing-the-new-manage-follows-endpoints-to-the-twitter-api-v2/149465",
"display_url": "devcommunity.com/t/introducing-…",
"images": \[\{
"url": "https://pbs.twimg.com/news\_img/1359554367905427457/DczC72\_\_?format=jpg&name=orig",
"width": 1200,
"height": 630
},
\{
"url": "https://pbs.twimg.com/news\_img/1359554367905427457/DczC72\_\_?format=jpg&name=150x150",
"width": 150,
"height": 150
}
\],
"status": 200,
"title": "Introducing the new manage follows endpoints to the X API v2",
"description": "To follow, or not to follow? You’re now free to answer that question however you like using the X API v2. Today, we’re excited to announce the release of the new manage follows endpoints into the new Twitter API. As teased when we launched the follows lookup endpoints a little over a month ago, the ability to manage follow relationships is finally here. These are some of our most popular endpoints on our v1.1 APIs, so we’re excited to unlock a wide range of use cases on X API v2. W...",
"unwound_url": "https://devcommunity.x.com/t/introducing-the-new-manage-follows-endpoints-to-the-twitter-api-v2/149465"
}\]
},
"context_annotations": \[\{
"domain": \{
"id": "46",
"name": "Brand Category",
"description": "Categories within Brand Verticals that narrow down the scope of Brands"
},
"entity": \{
"id": "781974596752842752",
"name": "Services"
}
},
\{
"domain": \{
"id": "47",
"name": "Brand",
"description": "Brands and Companies"
},
"entity": \{
"id": "10045225402",
"name": "Twitter"
}
}
\]
}\]
} | - -* * * - -#### User object - -| | | | -| :--- | :--- | :--- | -| **Twitter 1.1 format** | **Twitter v2 format** | **Required v2 parameters** | -| user_id | data.author_id | tweet.fields=author_id | -| user.id | | N/A use includes.users.id | -| user.id_str | includes.users.id | expansions=author_id | -| user.name | includes.users.name | expansions=author_id | -| user.screen_name | includes.user.username | expansions=author_id | -| user.location | includes.users.location | expansions=author_id&user.fields=location | -| user.description | includes.users.description | expansions=author_id&user.fields=description | -| user.url | includes.users.url | expansions=author_id&user.fields=entities | -| user.entities | includes.users.entities | | -| user.entities.url.urls.url | includes.users.entities.url.urls.url | | -| user.entities.url.urls.expanded_url | includes.users.entities.url.urls.expanded_url | expansions=author_id&user.fields=entities | -| user.entities.url.urls.display_url | includes.users.entities.url.urls.display_url | expansions=author_id&user.fields=entities | -| user.entities.url.urls.display_url.indicies\[0\] | includes.users.entities.url.urls.start | expansions=author_id&user.fields=entities | -| user.entities.url.urls.display_url.indicies\[1\] | includes.users.entities.url.urls.end | expansions=author_id&user.fields=entities | -| user.protected | includes.users.protected | expansions=author_id&user.fields=protected | -| user.followers_count | includes.users.public\_metrics.followers\_count | expansions=author\_id&user.fields=public\_metrics | -| user.friends_count | includes.users.public\_metrics.following\_count | expansions=author\_id&user.fields=public\_metrics | -| user.listed_count | includes.users.public\_metrics.listed\_count | expansions=author\_id&user.fields=public\_metrics | -| user.created_at | includes.users.created_at | expansions=author\_id&user.fields=created\_at | -| user.favourites_count | | | -| user.verified | includes.users.verified | expansions=author_id&user.fields=verified | -| user.statuses_count | includes.users.public\_metrics.tweet\_count | expansions=author\_id&user.fields=public\_metrics | -| user.profile\_image\_url_https | includes.users.profile\_image\_url | expansions=author\_id&user.fields=profile\_image_url | - -**Example** - -| | | -| :--- | :--- | -| **User object in 1.1** | **User object and request with v2** | -| "user": \{
"id": 2244994945,
"id_str": "2244994945",
"name": "Twitter Dev",
"screen_name": "TwitterDev",
"location": "127.0.0.1",
"description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.",
"url": "https:\\/\\/t.co\\/3ZX3TNiZCY",
"entities": \{
"url": \{
"urls": \[\{
"url": "https:\\/\\/t.co\\/3ZX3TNiZCY",
"expanded_url": "https:\\/\\/developer.x.com\\/en\\/community",
"display_url": "developer.x.com\\/en\\/community",
"indices": \[
0,
23
\]
}\]
},
"description": \{
"urls": \[\]
}
},
"protected": false,
"followers_count": 517232,
"friends_count": 2032,
"listed_count": 1722,
"created_at": "Sat Dec 14 04:35:55 +0000 2013",
"favourites_count": 2134,
"utc_offset": null,
"time_zone": null,
"geo_enabled": true,
"verified": true,
"statuses_count": 3677,
"lang": null,
"contributors_enabled": false,
"is_translator": false,
"is\_translation\_enabled": false,
"profile\_background\_color": "FFFFFF",
"profile\_background\_image_url": "http:\\/\\/abs.twimg.com\\/images\\/themes\\/theme1\\/bg.png",
"profile\_background\_image\_url\_https": "https:\\/\\/abs.twimg.com\\/images\\/themes\\/theme1\\/bg.png",
"profile\_background\_tile": false,
"profile\_image\_url": "http:\\/\\/pbs.twimg.com\\/profile\_images\\/1354494203451961345\\/d8HkZl6p\_normal.jpg",
"profile\_image\_url\_https": "https:\\/\\/pbs.twimg.com\\/profile\_images\\/1354494203451961345\\/d8HkZl6p_normal.jpg",
"profile\_banner\_url": "https:\\/\\/pbs.twimg.com\\/profile_banners\\/2244994945\\/1611792896",
"profile\_link\_color": "0084B4",
"profile\_sidebar\_border_color": "FFFFFF",
"profile\_sidebar\_fill_color": "DDEEF6",
"profile\_text\_color": "333333",
"profile\_use\_background_image": false,
"has\_extended\_profile": true,
"default_profile": false,
"default\_profile\_image": false,
"following": null,
"follow\_request\_sent": null,
"notifications": null,
"translator_type": "regular"
} | \{
"data": \[\{
"author_id": "2244994945",
"id": "1362876655061073928",
"text": "From our living rooms to yours 🐱‍💻🛋️Our developer advocates have some exciting Twitch streams and virtual events planned to help you get started with the new #TwitterAPI. Check out the schedule for details, and let us know if you want to see more!\\n👇\\nhttps://t.co/cixDY9qkvH"
}\],
"includes": \{
"users": \[\{
"public_metrics": \{
"followers_count": 517233,
"following_count": 2034,
"tweet_count": 3677,
"listed_count": 1727
},
"username": "TwitterDev",
"entities": \{
"url": \{
"urls": \[\{
"start": 0,
"end": 23,
"url": "https://t.co/3ZX3TNiZCY",
"expanded_url": "https://developer.x.com/en/community",
"display_url": "developer.x.com/en/community"
}\]
},
"description": \{
"hashtags": \[\{
"start": 17,
"end": 28,
"tag": "TwitterDev"
},
\{
"start": 105,
"end": 116,
"tag": "TwitterAPI"
}
\]
}
},
"description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.",
"name": "Twitter Dev",
"verified": true,
"location": "127.0.0.1",
"id": "2244994945",
"protected": false,
"url": "https://t.co/3ZX3TNiZCY",
"profile\_image\_url": "https://pbs.twimg.com/profile\_images/1354494203451961345/d8HkZl6p\_normal.jpg",
"created_at": "2013-12-14T04:35:55.000Z"
}\]
}
} | - -#### Entities and expanded entities objects - -| | | | | -| :--- | :--- | :--- | :--- | -| **Twitter 1.1 format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| entities | data.entities | tweet.fields=entities | object | -| entities.hashtags | data.entities.hashtags | tweet.fields=entities | array of objects | -| entities.hashtags.indices\[0\] | data.entities.hashtags.start | tweet.fields=entities | number | -| entities.hashtags.indices\[1\] | data.entities.hashtags.end | tweet.fields=entities | number | -| entities.hashtags.text | data.entities.hashtags.tag | tweet.fields=entities | string | -| entities.urls | data.entities.urls | tweet.fields=entities | array of objects | -| entities.urls.indices\[0\] | data.entities.urls.start | tweet.fields=entities | number | -| entities.urls.indices\[1\] | data.entities.urls.end | tweet.fields=entities | number | -| entities.urls.url | data.entities.urls.url | tweet.fields=entities | string | -| entities.user_mentions | data.entities.mentions | tweet.fields=entities | array of objects | -| entities.user_mentions.indicies\[0\] | data.entities.mentions.start | tweet.fields=entities | number | -| entities.user_mentions.indicies\[1\] | data.entities.mentions.end | tweet.fields=entities | number | -| entities.user\_mentions.screen\_name | data.entities.mentions.username | tweet.fields=entities | string | -| entities.symbols | data.entities.cashtags | tweet.fields=entities | array of objects | -| entities.symbols.indices\[0\] | data.entities.cashtags.start | tweet.fields=entities | number | -| entities.symbols.indices\[1\] | data.entities.cashtags.end | tweet.fields=entities | number | -| entities.symbols.text | data.entities.cashtags.tag | tweet.fields=entities | string | -| entities.media | includes.media | expansions=attachments.media_keys | array of objects | -| entities.media.id_str | includes.media.media_key | expansions=attachments.media_keys | string | -| entities.media.type | includes.media.media.type | expansions=attachments.media_keys | string | -| entities.media.media_url | | N/A use includes.media.url | string | -| entities.media.media\_url\_https | includes.media.url | expansions=attachments.media_keys&media.fields=url | string | -| entities.media.url | | | | -| entities.media.display_url | | | | -| entities.media.expanded_url | | | | -| entities.media.media\_url\_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | string | -| extended_entities | data.attachments | tweet_fields=attachments | object | -| extended_entities | data.attachments.media_keys | tweet.fields=attachments | array of objects | -| extended_entities.media | includes.media | expansions=attachments.media_keys | array of objects | -| extended\_entities.media.id\_str | includes.media.media_key | expansions=attachments.media_keys | string | -| extended_entities.media.type | includes.media.media.type | expansions=attachments.media_keys | string | -| extended_entities.media.sizes.thumb.w | | Not Available | | -| extended_entities.media.sizes.thumb.h | | Not Available | | -| extended_entities.media.sizes.thumb.resize | | Not Available | | -| extended_entities.media.sizes.large.w | includes.media.height | expansions=attachments.media_keys&media.fields=height | | -| extended_entities.media.sizes.large.h | includes.media.width | expansions=attachments.media_keys&media.fields=width | | -| extended_entities.media.sizes.large.resize | | Not Available | | -| extended_entities.media.sizes.small.w | | Not Available | | -| extended_entities.media.sizes.small.h | | Not Available | | -| extended_entities.media.sizes.small.resize | | Not Available | | -| extended_entities.media.sizes.medium.w | | Not Available | | -| extended_entities.media.sizes.medium.h | | Not Available | | -| extended_entities.media.sizes.medium.resize | | Not Available | | -| extended\_entities.media.media\_url_https | includes.media.url | expansions=attachments.media_keys&media.fields=url | string | -| extended\_entities.media.media\_url_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | string | -| extended\_entities.media.video\_info.duration_millis | includes.media.duration_ms | expansions=attachments.media\_keys&media.fields=duration\_ms | number | - -**Example** - -| | | -| :--- | :--- | -| **Entities and extended entities in v1.1 (with video)** | **Entities, attachments and includes in v2**

https://api.x.com/2/tweets?ids=1370161532013735937&expansions=attachments.media\_keys,entities.mentions.username&tweet.fields=entities&user.fields=created\_at,description,entities,location,name,profile\_image\_url,protected,public\_metrics,url,username,verified,withheld&media.fields=duration\_ms,height,media\_key,preview\_image\_url,public\_metrics,type,url,width | -| "entities": \{
"hashtags": \[\{
"text": "test",
"indices": \[
8,
13
\]
}\],
"symbols": \[\],
"user_mentions": \[\{
"screen_name": "TwitterDev",
"name": "Twitter Dev",
"id": 2244994945,
"id_str": "2244994945",
"indices": \[
31,
42
\]
}\],
"urls": \[\{
"url": "https:\\/\\/t.co\\/XVLZ3uwikc",
"expanded_url": "https:\\/\\/developer.x.com\\/en",
"display_url": "developer.x.com\\/en",
"indices": \[
91,
114
\]
}\],
"media": \[\{
"id": 1370161464028196868,
"id_str": "1370161464028196868",
"indices": \[
115,
138
\],
"media\_url": "http:\\/\\/pbs.twimg.com\\/ext\_tw\_video\_thumb\\/1370161464028196868\\/pu\\/img\\/cGLCoXBHVktkwlC5.jpg",
"media\_url\_https": "https:\\/\\/pbs.twimg.com\\/ext\_tw\_video_thumb\\/1370161464028196868\\/pu\\/img\\/cGLCoXBHVktkwlC5.jpg",
"url": "https:\\/\\/t.co\\/dz4oByygWA",
"display_url": "pic.x.com\\/dz4oByygWA",
"expanded_url": "https:\\/\\/twitter.com\\/furiouscamper\\/status\\/1370161532013735937\\/video\\/1",
"type": "photo",
"sizes": \{
"thumb": \{
"w": 150,
"h": 150,
"resize": "crop"
},
"small": \{
"w": 383,
"h": 680,
"resize": "fit"
},
"large": \{
"w": 720,
"h": 1280,
"resize": "fit"
},
"medium": \{
"w": 675,
"h": 1200,
"resize": "fit"
}
}
}\]
},
"extended_entities": \{
"media": \[\{
"id": 1370161464028196868,
"id_str": "1370161464028196868",
"indices": \[
115,
138
\],
"media\_url": "http:\\/\\/pbs.twimg.com\\/ext\_tw\_video\_thumb\\/1370161464028196868\\/pu\\/img\\/cGLCoXBHVktkwlC5.jpg",
"media\_url\_https": "https:\\/\\/pbs.twimg.com\\/ext\_tw\_video_thumb\\/1370161464028196868\\/pu\\/img\\/cGLCoXBHVktkwlC5.jpg",
"url": "https:\\/\\/t.co\\/dz4oByygWA",
"display_url": "pic.x.com\\/dz4oByygWA",
"expanded_url": "https:\\/\\/twitter.com\\/furiouscamper\\/status\\/1370161532013735937\\/video\\/1",
"type": "video",
"sizes": \{
"thumb": \{
"w": 150,
"h": 150,
"resize": "crop"
},
"small": \{
"w": 383,
"h": 680,
"resize": "fit"
},
"large": \{
"w": 720,
"h": 1280,
"resize": "fit"
},
"medium": \{
"w": 675,
"h": 1200,
"resize": "fit"
}
},
"video_info": \{
"aspect_ratio": \[
9,
16
\],
"duration_millis": 5140,
"variants": \[\{
"bitrate": 950000,
"content_type": "video\\/mp4",
"url": "https:\\/\\/video.twimg.com\\/ext\_tw\_video\\/1370161464028196868\\/pu\\/vid\\/480x852\\/rAuFVMEqs0MeP4P4.mp4?tag=12"
},
\{
"bitrate": 2176000,
"content_type": "video\\/mp4",
"url": "https:\\/\\/video.twimg.com\\/ext\_tw\_video\\/1370161464028196868\\/pu\\/vid\\/720x1280\\/ZxVL5qYO-DNVuSyq.mp4?tag=12"
},
\{
"content_type": "application\\/x-mpegURL",
"url": "https:\\/\\/video.twimg.com\\/ext\_tw\_video\\/1370161464028196868\\/pu\\/pl\\/EGVpuZpo-wYxTNCq.m3u8?tag=12"
},
\{
"bitrate": 632000,
"content_type": "video\\/mp4",
"url": "https:\\/\\/video.twimg.com\\/ext\_tw\_video\\/1370161464028196868\\/pu\\/vid\\/320x568\\/M7VtocAwKPFdkqzF.mp4?tag=12"
}
\]
},
"additional\_media\_info": \{
"monetizable": false
}
}\]
} | \{
"data": \[\{
"entities": \{
"hashtags": \[\{
"start": 8,
"end": 13,
"tag": "test"
}\],
"mentions": \[\{
"start": 31,
"end": 42,
"username": "TwitterDev"
}\],
"urls": \[\{
"start": 91,
"end": 114,
"url": "https://t.co/XVLZ3uwikc",
"expanded_url": "https://developer.x.com/en",
"display_url": "developer.x.com/en",
"status": 200,
"title": "Use Cases, Tutorials, & Documentation",
"description": "Publish & analyze Tweets, optimize ads, & create unique customer experiences with the Twitter API, Twitter Ads API, & Twitter for Websites. Let's start building.",
"unwound_url": "https://developer.x.com/en"
},
\{
"start": 115,
"end": 138,
"url": "https://t.co/dz4oByygWA",
"expanded_url": "https://x.com/furiouscamper/status/1370161532013735937/video/1",
"display_url": "pic.x.com/dz4oByygWA"
}
\]
},
"id": "1370161532013735937",
"text": "Another #test with a video and @TwitterDev mention. Excited for new format migration docs! https://t.co/XVLZ3uwikc https://t.co/dz4oByygWA",
"attachments": \{
"media_keys": \[
"7_1370161464028196868"
\]
}
}\],
"includes": \{
"media": \[\{
"type": "video",
"height": 1280,
"public_metrics": \{
"view_count": 37
},
"width": 720,
"media\_key": "7\_1370161464028196868",
"duration_ms": 5140,
"preview\_image\_url": "https://pbs.twimg.com/ext\_tw\_video_thumb/1370161464028196868/pu/img/cGLCoXBHVktkwlC5.jpg"
}\],
"users": \[\{
"public_metrics": \{
"followers_count": 517233,
"following_count": 2034,
"tweet_count": 3677,
"listed_count": 1727
},
"created_at": "2013-12-14T04:35:55.000Z",
"profile\_image\_url": "https://pbs.twimg.com/profile\_images/1354494203451961345/d8HkZl6p\_normal.jpg",
"description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.",
"verified": true,
"id": "2244994945",
"username": "TwitterDev",
"protected": false,
"entities": \{
"url": \{
"urls": \[\{
"start": 0,
"end": 23,
"url": "https://t.co/3ZX3TNiZCY",
"expanded_url": "https://developer.x.com/en/community",
"display_url": "developer.x.com/en/community"
}\]
},
"description": \{
"hashtags": \[\{
"start": 17,
"end": 28,
"tag": "TwitterDev"
},
\{
"start": 105,
"end": 116,
"tag": "TwitterAPI"
}
\]
}
},
"url": "https://t.co/3ZX3TNiZCY",
"name": "Twitter Dev",
"location": "127.0.0.1"
}\]
}
} | - -* * * - -#### Place object - -| | | | -| :--- | :--- | :--- | -| **Twitter 1.1 format** | **Twitter v2 format** | **Required v2 parameters** | -| place | data.geo.place_id | tweet.fields=geo | -| place.id | includes.places.id | expansions=geo.place_id | -| place.id.place_type | includes.places.place_type | expansions=geo.place\_id&place.fields=place\_type | -| place.id.name | includes.places.name | expansions=geo.place_id&place.fields=name | -| place.id.full_name | includes.places.full_name | expansions=geo.place_id | -| place.id.country_code | includes.places.country_code | expansions=geo.place\_id&place.fields=country\_code | -| place.id.country | includes.places.country | expansions=geo.place_id&place.fields=country | -| place.id.contained_within | includes.places.contained_within | expansions=geo.place\_id&place.fields=contained\_within | -| place.id.bounding_box.type | includes.places.geo.type | expansions=geo.place\_id&place.fields=place\_type | -| place.id.bounding_box.coordinates | includes.places.geo.bbox | expansions=geo.place_id&place.fields=geo | -| place.id.attributes | includes.places.properties | expansions=geo.place_id&place.fields=geo | - -**Example** - -| | | -| :--- | :--- | -| **Place object in v1.1** | **Place object with v2**

https://api.x.com/2/tweets?ids=1370161532013735937&expansions=geo.place\_id&tweet.fields=geo&place.fields=contained\_within,country,country\_code,full\_name,geo,id,name,place_type | -| "place": \{
"id": "f7eb2fa2fea288b1",
"url": "https:\\/\\/api.x.com\\/1.1\\/geo\\/id\\/f7eb2fa2fea288b1.json",
"place_type": "city",
"name": "Lakewood",
"full_name": "Lakewood, CO",
"country_code": "US",
"country": "United States",
"contained_within": \[\],
"bounding_box": \{
"type": "Polygon",
"coordinates": \[
\[
\[
-105.193475,
39.60973
\],
\[
-105.053164,
39.60973
\],
\[
-105.053164,
39.761974
\],
\[
-105.193475,
39.761974
\]
\]
\]
},
"attributes": {}
} | \{
"data": \[\{
"id": "1370161532013735937",
"text": "Another #test with a video and @TwitterDev mention. Excited for new format migration docs! https://t.co/XVLZ3uwikc https://t.co/dz4oByygWA",
"geo": \{
"place_id": "f7eb2fa2fea288b1"
}
}\],
"includes": \{
"places": \[\{
"name": "Lakewood",
"place_type": "city",
"full_name": "Lakewood, CO",
"id": "f7eb2fa2fea288b1",
"geo": \{
"type": "Feature",
"bbox": \[
-105.193475,
39.60973,
-105.053164,
39.761974
\],
"properties": {}
},
"country_code": "US",
"country": "United States"
}\]
} | - -**Next step** - -* Learn more about [fields](/x-api/fundamentals/fields) -* Learn more about [expansions](/x-api/fundamentals/expansions) -* Learn how to [use fields with expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) - - -### Migrating from Native Enriched data format to v2 - -The Native Enriched data format is used by our [enterprise](/x-api/enterprise-gnip-2.0/enterprise-gnip) products. - -The Native Enriched data format has been updated to provide edited Tweet metadata. To learn more about Edit Tweet metadata, check out the [Edit Tweets fundamentals](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) page. - -If you are using the standard v1.1 endpoints, please refer to the [standard v1.1 to v2 guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2). If you are using the enterprise products with Activity Streams, we have an [Activity Streams to v2](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) guide for you as well. - -X API v2 introduces new JSON designs for [Tweet](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the Native Enriched format returns Tweet objects in a results array, while X API v2 returns a data array.  -* Instead of using both favorites (in Tweet object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Tweet and user attributes are only included if they have non-null values.  -* All id fields in v2 will be in string format -   - -In addition to the changes made to the new JSON format, we also introduced a new set of fields to the Tweet object including the following: - -* conversation_id -* reply_settings -* alt_text on media -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields -* Several new [polls](/x-api/fundamentals/data-dictionary#poll) fields -   - -Many legacy and deprecated fields are being removed: - -* contributors -* Certain entities.media and extended_entities.media fields -* filter_level -* timestamp_ms -* truncated - -#### Native Enriched vs v2 payload structure - -The following table displays the high-level objects and format that you can expect to receive from v2 compared to the Native Enriched format. - -| | **Native Enriched structure** | **v2 structure** | -| :--- | :--- | :--- | -| **Default** | \{
~tweet object fields~,

"user": {},
"place": {},
"entities": \{
"hashtags": \[\],
"urls": \[\],
"user_mentions": \[\],
"symbols": \[\],
"annotations": \[\],
"media": \[\]
},
"extended_entities": {},
"matching_rules": \[\]
} | \{
"data": \[\{
"id",
"text",

"edit\_history\_tweet_ids"
}\]
} | -| **With defined [field and expansion](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) parameters** | | \{
"data": \[\{
~tweet object fields~,
"entities": \{
"hashtags": \[\],
"cashtags": \[\],
"mentions": \[\],
"urls": \[\],
},
"attachments": \{
"media_keys": \[\],
"poll_ids": \[\]
}
}\],
"includes": \[
"tweets": \[~user objects~\],
"users": \[~user objects~\],
"media": \[~media objects~\],
"places": \[~place object~\],
"polls": \[~poll object~\]
\],
"matching_rules": \[\]
} | - -**Field mapping** - -The following section describes which native enriched fields map to v2 fields, as well as which v2 parameters are required to receive the new field. -  - -#### Tweet object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| created_at | data.created_at | tweet.fields=created_at | String | -| id | | N/A - See id | | -| id_str | data.id | Default | String | -| text | data.text | Default | String | -| edit_history | data.edit\_history\_tweet_ids | Default | Array | -| edit_controls | data.edit_controls | tweet.fields=edit_controls | Object | -| editable | data.edit\_controls.is\_edit_eligible | tweet.fields=edit_controls | Boolean | -| display\_text\_range | | N/A - text includes complete text | | -| source | data.source | tweet.fields=source | String | -| truncated | | N/A - text includes complete text | | -| Not available | data.conversation_id | tweet.fields=conversation_id | String | -| Not available | data.reply_settings | tweet.fields=reply_settings | String | -| in\_reply\_to\_status\_id | | N/A - See referenced_tweets.id | | -| in\_reply\_to\_status\_id_str | data.referenced_tweets.id (if type=replied_to) | expansions=referenced_tweets.id | String | -| in\_reply\_to\_user\_id | | N/A - See in\_reply\_to\_user\_id_str | | -| in\_reply\_to\_user\_id_str | data.in\_reply\_to\_user\_id | tweet.fields=in\_reply\_to\_user\_id | String | -| in\_reply\_to\_screen\_name | includes.users..username | tweet.fields=in\_reply\_to\_user\_id&expansions=entities.mentions.username | String | -| user | includes.users | expansions=author_id | Object | -| user.id_str | data.author_id | tweet.fields=author_id | String | -| geo | data.geo.place_id | tweet.fields=geo | | -| coordinates | data.geo.place_id | tweet.fields=geo | | -| place | data.geo.place_id | tweet.fields=geo | | -| is\_quoted\_status | data.referenced_tweets.id (if type=quoted) | tweet.fields=referenced_tweets | String | -| extended\_tweet.full\_text | | N/A - text is complete text | | -| Not available | data.public_metrics | tweet.fields=public_metrics | Object | -| quote_count | data.public\_metrics.quote\_count | tweet.fields=public_metrics | Int | -| reply_count | data.public\_metrics.reply\_count | tweet.fields=public_metrics | Int | -| retweet_count | data.public\_metrics.retweet\_count | tweet.fields=public_metrics | Int | -| favorite_count | data.public\_metrics.like\_count | tweet.fields=public_metrics | Int | -| Not available | data.non\_public\_metrics | tweet.fields=non\_public\_metrics | Object | -| Not available | data.non\_public\_metrics.impression_count | tweet.fields=non\_public\_metrics | Int | -| Not available | data.non\_public\_metrics.url\_link\_count | tweet.fields=non\_public\_metrics | Int | -| Not available | data.non\_public\_metrics.user\_profile\_count | tweet.fields=non\_public\_metrics | Int | -| Not available | data.organic_metrics | tweet.fields=organic_metrics | Object | -| Not available | data.organic\_metrics.like\_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.retweet\_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.reply\_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.impression\_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.url\_link_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.user\_profile_count | tweet.fields=organic_metrics | Int | -| Not available | data.promoted_metrics | tweet.fields=promoted_metrics | Object | -| Not available | data.promoted\_metrics.like\_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.retweet\_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.reply\_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.impression\_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.url\_link_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.user\_profile_count | tweet.fields=promoted_metrics | Int | -| contributors | Not available | Not available | | -| entities | data.entities | tweet.fields=entities | Object | -| entities.user_mentions | data.entities.mentions | tweet.fields=entities | Array of objects | -| entities.symbols | data.entities.cashtags | tweet.fields=entities | Array of objects | -| entities.hashtags | data.entities.hashtags | tweet.fields=entities | Array of objects | -| entities.urls | data.entities.urls | tweet.fields=entities | Array of objects | -| entities.media | includes.media | expansions=attachments.media_keys | Array of objects | -| entities.annotations | | tweet.fields=entities,context_annotations | Object | -| entities.annotations.context | data.context_annotations | tweet.fields=entities,context_annotations | Array of objects | -| No equivalent | data.context_annotations.domain | tweet.fields=context_annotations | Object | -| entities.annotations.context.context\_domain\_id_str | data.context_annotations.domain.id | tweet.fields=context_annotations | String | -| entities.annotations.context.context\_domain\_id | Not available | Not available - see data.context_annotations.domain.id for string format | | -| entities.annotations.context.context\_domain\_name | data.context_annotations.domain.name | tweet.fields=context_annotations | String | -| entities.annotations.context.context\_domain\_description | data.context_annotations.domain.description | tweet.fields=context_annotations | String | -| No equivalent | data.context_annotations.entity | tweet.fields=context_annotations | Object | -| entities.annotations.context.context\_entity\_id_str | data.context_annotations.entity.id | tweet.fields=context_annotations | String | -| entities.annotations.context.context\_entity\_id | Not available | Not available - see data.context_annotations.entity.id for string format | | -| entities.annotations.context.context\_entity\_name | data.context_annotations.entity.name | tweet.fields=context_annotations | String | -| entities.annotations.context.context\_entity\_description | data.context_annotations.entity.description | tweet.fields=context_annotations | String | -| entities.annotations.entity | data.entities.annotations | tweet.fields=entities,context_annotations | Array of objects | -| extended_entities | data.attachments | tweet_fields=attachments | Object | -| favorited | Not available | Not available | | -| retweeted | Not available | Not available | | -| retweeted_status | | | | -| possibly_sensitive | data.possibly_sensitive | tweet.fields=possibly_sensitive | Boolean | -| lang | data.lang | tweet.fields=lang | String | -| filter_level | Not available | Not available | | -| scopes | Not available | Not available | | -| timestamp_ms | Not available | Not available | | -| withheld | data.withheld | tweet.fields=withheld | Array of objects | -| matching_rules | matching_rules | | Array of objects | -| matching_rules.id | Not available | Not available | | -| matching\_rules.id\_str | matching_rules.id | Default with filtered stream | String | -| matching_rules.tag | matching_rules.tag | Default with filtered stream | String | - -#### User object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| user | includes.users | expansions=author_id | Array of objects | -| user.id | Not available | N/A - See includes.users.id | String | -| user.id_str | includes.users.id | expansions=author_id | String | -| user.name | includes.users.name | expansions=author_id | String | -| user.screen_name | includes.user.username | expansions=author_id | String | -| user.location | includes.users.location | expansions=author_id&user.fields=location | Object | -| user.description | includes.users.description | expansions=author_id&user.fields=description | String | -| Not available | includes.users.url | expansions=author_id&user.fields=url | String | -| user.followers_count | includes.users.public\_metrics.followers\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| user.friends_count | includes.users.public\_metrics.following\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| user.listed_count | includes.users.public\_metrics.listed\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| user.created_at | includes.users.created_at | expansions=author\_id&user.fields=created\_at | String | -| user.favourites_count | | Not yet available | | -| user.verified | includes.users.verified | expansions=author_id&user.fields=verified | Boolean | -| Not available | includes.users.pinned\_tweet\_id | expansions=author\_id&user.fields=pinned\_tweet_id | String | -| user.statuses_count | includes.users.public\_metrics.tweet\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| user.profile\_image\_url_https | includes.users.profile\_image\_url | expansions=author\_id&user.fields=profile\_image_url | String | -| user.translator_type | Not available | Not available | | -| user.utc_offset | Not available | Not available | | -| user.time_zone | Not available | Not available | | -| user.geo_enabled | Not available | Not available | | -| user.lang | Not available | Not available - infer from Tweet lang | | -| user.contributors_enabled | Not available | Not available | | -| user.is_translator | Not available | Not available | | -| user.profile\_background\_color | Not available | Not available | | -| user.profile\_background\_image_url | Not available | Not available | | -| user.profile\_background\_image\_url\_https | Not available | Not available | | -| user.profile\_background\_title | Not available | Not available | | -| user.profile\_sidebar\_border_color | Not available | Not available | | -| user.profile\_sidebar\_fill_color | Not available | Not available | | -| user.profile\_text\_color | Not available | Not available | | -| user.profile\_user\_background_image | Not available | Not available | | -| user.profile\_image\_url | | See includes.user.profile\_image\_url | | -| user.default_profile | Not available | Not available | | -| user.default\_profile\_image | Not available | Not available | | -| user.following | Not available | Not available | | -| user.follow\_request\_sent | Not available | Not available | | -| user.notifications | Not available | Not available | | -| user.withheld\_in\_countries | includes.users.withheld | expansions=author_id&user.fields=withheld | Object | -| user.protected | includes.users.protected | expansions=author_id&user.fields=protected | Boolean | -| Not available | includes.users.entities | expansions=author_id&user.fields=entities | Object | -| Not available | includes.users.entities.url | expansions=author_id&user.fields=entities | Object | -| Not available | includes.users.entities.url.urls | expansions=author_id&user.fields=entities | Array of objects | -| Not available | includes.users.entities.url.urls.start | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.url.urls.end | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.url.urls.url | expansions=author_id&user.fields=entities | String | -| user.url | includes.users.entities.url.urls.expanded_url | expansions=author_id&user.fields=entities | String | -| Not available | includes.users.entities.url.urls.display_url | expansions=author_id&user.fields=entities | String | -| Not available | includes.users.entities.descriptions | expansions=author_id&user.fields=entities | Object | -| Not available | includes.users.entities.descriptions.hashtags | expansions=author_id&user.fields=entities | Array of objects | -| Not available | includes.users.entities.descriptions.hashtags.start | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.descriptions.hashtags.end | expansions=author_id&user.fields=entities | Int | -| included in user.description | includes.users.entities.descriptions.hashtags.tag | expansions=author_id&user.fields=entities | String | -| Not available | includes.users.entities.descriptions.mentions | expansions=author_id&user.fields=entities | Array of objects | -| Not available | includes.users.entities.descriptions.mentions.start | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.descriptions.mentions.end | expansions=author_id&user.fields=entities | Int | -| Included in user.description | includes.users.entities.descriptions.mentions.username | expansions=author_id&user.fields=entities | String | -| Not available | includes.users.entities.descriptions.cashtags | expansions=author_id&user.fields=entities | Array of objects | -| Not available | includes.users.entities.descriptions.cashtags.start | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.descriptions.cashtags.end | expansions=author_id&user.fields=entities | Int | -| Included in user.description | includes.users.entities.descriptions.cashtags.tag | expansions=author_id&user.fields=entities | String | - -#### Entities and expanded entities objects - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| entities | data.entities | tweet.fields=entities | Object | -| entities.hashtags | data.entities.hashtags | tweet.fields=entities | Array of objects | -| entities.hashtags.indices\[0\] | data.entities.hashtags.start | tweet.fields=entities | Integer | -| entities.hashtags.indices\[1\] | data.entities.hashtags.end | tweet.fields=entities | Integer | -| entities.hashtags.text | data.entities.hashtags.tag | tweet.fields=entities | String | -| entities.urls | data.entities.urls | tweet.fields=entities | Array of objects | -| entities.urls.indices\[0\] | data.entities.urls.start | tweet.fields=entities | Integer | -| entities.urls.indices\[1\] | data.entities.urls.end | tweet.fields=entities | Integer | -| entities.urls.url | data.entities.urls.url | tweet.fields=entities | String | -| entities.urls.expanded_url | data.entities.urls.expanded_url | tweet.fields=entities | String | -| entities.urls.display_url | data.entities.urls.display_url | tweet.fields=entities | String | -| entities.urls.unwound.url | data.entities.urls.unwound_url | tweet.fields=entities | String | -| entities.urls.unwound.status | data.entities.urls.status | tweet.fields=entities | String | -| entities.urls.unwound.title | data.entities.urls.title | tweet.fields=entities | String | -| entities.urls.unwound.description | data.entities.urls.description | tweet.fields=entities | String | -| Not available | data.entities.urls.images | tweet.fields=entities | Array of objects | -| Not available | data.entities.urls.images.url | tweet.fields=entities | String | -| Not available | data.entities.urls.images.width | tweet.fields=entities | Int | -| Not available | data.entities.urls.images.height | tweet.fields=entities | Int | -| entities.user_mentions | data.entities.mentions | tweet.fields=entities | Array of objects | -| entities.user_mentions.indicies\[0\] | data.entities.mentions.start | tweet.fields=entities | Integer | -| entities.user_mentions.indicies\[1\] | data.entities.mentions.end | tweet.fields=entities | Integer | -| entities.user\_mentions.screen\_name | data.entities.mentions.username | tweet.fields=entities | String | -| entities.symbols | data.entities.cashtags | tweet.fields=entities | Array of objects | -| entities.symbols.indices\[0\] | data.entities.cashtags.start | tweet.fields=entities | Integer | -| entities.symbols.indices\[1\] | data.entities.cashtags.end | tweet.fields=entities | Integer | -| entities.symbols.text | data.entities.cashtags.tag | tweet.fields=entities | String | -| entities.media OR extended_entities.media | includes.media | expansions=attachments.media_keys | Array of objects | -| entities.media.id_str OR extended\_entities.media.id\_str | includes.media.media_key | expansions=attachments.media_keys | String | -| entities.media.id OR extended_entities.media.id | | Not available - id is a String | | -| entities.media.type OR extended_entities.media.type | includes.media.media.type | expansions=attachments.media_keys | String | -| entities.media.indices OR extended_entities.media.indices | Not available | Not available | | -| Not available | includes.media.alt_text | expansions=attachments.media\_keys&media.fields=alt\_text | String | -| entities.media.additional\_media\_info OR extended\_entities.media.additional\_media_info | Not available | Not available | | -| entities.media.additional\_media\_info.monetizable OR extended\_entities.media.additional\_media_info.monetizable | Not available | Not available | | -| entities.media.media_url OR extended\_entities.media.media\_url | | N/A - See includes.media.url | String | -| entities.media.media\_url\_https OR extended\_entities.media.media\_url_https | includes.media.url | expansions=attachments.media_keys&media.fields=url | String | -| entities.media.url OR extended_entities.media.url | | | | -| entities.media.display_url OR extended\_entities.media.expanded\_url | | | | -| entities.media.expanded_url | | | | -| entities.media.media\_url\_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | String | -| extended_entities | data.attachments | tweet_fields=attachments | Object | -| extended_entities | data.attachments.media_keys | tweet.fields=attachments | Array of objects | -| Not available | data.attachments.poll_ids | tweet.fields=attachments | Array of objects | -| extended_entities.media.sizes.thumb.w | | Not Available | | -| extended_entities.media.sizes.thumb.h | | Not Available | | -| extended_entities.media.sizes.thumb.resize | | Not Available | | -| extended_entities.media.sizes.large.w | includes.media.height | expansions=attachments.media_keys&media.fields=height | | -| extended_entities.media.sizes.large.h | includes.media.width | expansions=attachments.media_keys&media.fields=width | | -| extended_entities.media.sizes.large.resize | Not Available | Not Available | | -| extended_entities.media.sizes.small.w | Not Available | Not Available | | -| extended_entities.media.sizes.small.h | Not Available | Not Available | | -| extended_entities.media.sizes.small.resize | Not Available | Not Available | | -| extended_entities.media.sizes.medium.w | Not Available | Not Available | | -| extended_entities.media.sizes.medium.h | Not Available | Not Available | | -| extended_entities.media.sizes.medium.resize | Not Available | Not Available | | -| extended\_entities.media.media\_url_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | String | -| extended\_entities.media.video\_info.aspect_ratio | Not available | Not available | | -| extended_entities.media.variants | Not available | Not available | | -| extended_entities.media.variants.bitrate | Not available | Not available | | -| extended\_entities.media.variants.content\_type | Not available | Not available | | -| extended_entities.media.variants.url | Not available | Not available | | -| extended\_entities.media.video\_info.duration_millis | includes.media.duration_ms | expansions=attachments.media\_keys&media.fields=duration\_ms | Int | -| Not available | includes.media.public_metrics | expansions=attachments.media\_keys&media.fields=public\_metrics | Object | -| Not available | includes.media.public\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=public\_metrics | Int | -| Not available | includes.media.non\_public\_metrics | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Object | -| Not available | includes.media.non\_public\_metrics.playback\_0\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_25\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_50\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_75\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_100\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.organic_metrics | expansions=attachments.media\_keys&media.fields=organic\_metrics | Object | -| Not available | includes.media.organic\_metrics.playback\_0_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_25_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_50_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_75_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_100_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.promoted_metric | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Object | -| Not available | includes.media.promoted\_metric.playback\_0_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metric.playback\_25_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metric.playback\_50_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metric.playback\_75_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metric.playback\_100_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | - -#### Place object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| place | includes.places | expansions=geo.place_id | Array of objects | -| place.id | includes.places.id | expansions=geo.place_id | String | -| place.url | Not available | Not available | | -| place.id.place_type | includes.places.place_type | expansions=geo.place\_id&place.fields=place\_type | String | -| place.id.name | includes.places.name | expansions=geo.place_id&place.fields=name | String | -| place.id.full_name | includes.places.full_name | expansions=geo.place_id | String | -| place.id.country_code | includes.places.country_code | expansions=geo.place\_id&place.fields=country\_code | String | -| place.id.country | includes.places.country | expansions=geo.place_id&place.fields=country | String | -| place.id.contained_within | includes.places.contained_within | expansions=geo.place\_id&place.fields=contained\_within | Array | -| place.id.bounding_box.type | includes.places.geo.type | expansions=geo.place\_id&place.fields=place\_type | String | -| place.id.bounding_box.coordinates | includes.places.geo.bbox | expansions=geo.place_id&place.fields=geo | Array | -| place.id.attributes | includes.places.properties | expansions=geo.place_id&place.fields=geo | Object | - -#### Poll object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| entities.polls | includes.polls | expansions=attachments.poll_ids | Array of objects | -| Not available | includes.polls.id | expansions=attachments.poll_ids | String | -| entities.poll.options | includes.polls.options | expansions=attachments.poll_ids | Array of objects | -| entities.polls.options.position | includes.polls.options.position | expansions=attachments.poll_ids | Int | -| entities.polls.options.text | includes.polls.options.label | expansions=attachments.poll_ids | String | -| Not available | includes.polls.options.votes | expansions=attachments.poll_ids | Int | -| Not available | includes.polls.voting_status | expansions=attachments.poll\_ids&poll.fields=voting\_status | String | -| entities.polls.duration_minutes | includes.polls.duration_minutes | expansions=attachments.poll\_ids&poll.fields=duration\_minutes | Int | -| entities.polls.end_datetime | includes.polls.end_datetime | expansions=attachments.poll\_ids&poll.fields=end\_datetime | Date (ISO 8601) | - - -### Migrating from Activity Streams data format to v2 - -The Activity Streams data format is available with our [enterprise](/x-api/enterprise-gnip-2.0/enterprise-gnip) products. - -The Activity Streams data format has been updated to provide edited Tweet metadata. To learn more about Edit Tweet metadata, check out the [Edit Tweets fundamentals](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) page. - -If you are using the standard v1.1 endpoints, please refer to the [standard v1.1 to v2 guide](/x-api/migrate/overview). If you are using the premium endpoints, or the Native Enriched format for enterprise, please refer to the [Native Enriched to v2 guide](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2). - -X API v2 introduces new JSON designs for [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the Activity Streams format returns Tweet objects in a results array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "activities", X API v2 JSON refers to Retweeted and Quoted Tweets.  -* Instead of using both favorites (in Tweet object) and favourites (in user object), X API v2 uses the term like.  -* Twitter is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Tweet and user attributes are only included if they have non-null values.  -* All id fields in v2 will be in string format. -   - -In addition to the changes made to the new JSON format, we also introduced a new set of fields to the Tweet object including the following: - -* conversation_id -* reply_settings -* alt_text on media -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields -* Several new [polls](/x-api/fundamentals/data-dictionary#poll) fields -   - -Many legacy and deprecated fields are being removed or replaced: - -* display\_text\_range -* generator -* gnip -* link -* objectType -* provider -* twitter_entities.symbols replaced with data.entities.cashtags -* Certain twitter\_extended\_entities.media and twitter_entities.media fields -* twitter\_filter\_level -* twitterTimeZone -* verb - -#### Tweet object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| postedTime | data.created_at | tweet.fields=created_at | Date (ISO 8601) | -| generator | Not Available | Not Available | | -| generator.link | Not Available | Not Available | | -| generator.displayName | data.source | tweet.fields=source | String | -| twitter_lang | data.lang | tweet.fields=lang | String | -| Not Available | data.conversation_id | tweet.fields=conversation_id | String | -| Not Available | data.reply_settings | tweet.fields=reply_settings | String | -| Not Available | data.possibly_sensitive | tweet.fields=possibly_sensitive | Boolean | -| Not Available | data.withheld | tweet.fields=withheld | Object | -| objectType | Not Available | Not Available | | -| verb | Not Available | Not Available | | -| provider | Not Available | Not Available | | -| provider.objectType | Not Available | Not Available | | -| provider.displayName | Not Available | Not Available | | -| provider.link | Not Available | Not Available | | -| link | Not Available | Not Available | | -| display\_text\_range | Not Available | Not Available | | -| object | Not Available | Not Available | | -| object.objectType | Not Available | Not Available | | -| object.id | Not Available | Not Available | | -| object.summary | data.text | default | String | -| object.edit_history | data.edit\_history\_tweet_ids | default | Array | -| object.edit_controls | data.edit_controls | tweet.fields=edit_controls | Object | -| object.editable | data.edit\_controls.is\_edit_eligible | tweet.fields=edit_controls | Boolean | -| object.link | Not Available | Not Available | | -| object.postedTime | data.created_at | tweet.fields=created_at | Date (ISO 8601) | -| Derived from actor.id | data.author_id | tweet.fields=created_at | | -| twitter\_filter\_level | Not Available | Not Available | | -| Derived from username in inReplyTo.link | data.in\_reply\_to\_user\_id | tweet.fields=in\_reply\_to\_user\_id | String | -| Not Available | data.referenced_tweets | tweet.fields=referenced_tweets | Array of objects | -| Not Available | data.referenced_tweets.type | tweet.fields=referenced_tweets | String | -| Derived from inReplyTo.link | data.referenced_tweets.id | tweet.fields=referenced_tweets | String | -| Not Available | data.attachments | tweet.fields=attachments | Object | -| Derived from twitter\_entities.media.id\_str | data.attachments.media_keys | tweet.fields=attachments | Array | -| Not Available | data.attachments.poll_ids | tweet.fields=attachments | Array | -| twitter_entities | data.entities | tweet.fields=entities | Object | -| Not Available | data.entities.annotations | tweet.fields=entities | Array of objects | -| Not Available | data.entities.annotations.start | tweet.fields=entities | Int | -| Not Available | data.entities.annotations.end | tweet.fields=entities | Int | -| Not Available | data.entities.annotations.probability | tweet.fields=entities | Float | -| Not Available | data.entities.annotations.type | tweet.fields=entities | String | -| Not Available | data.entities.annotations.normalized_text | tweet.fields=entities | String | -| twitter_entities.urls | data.entities.urls | tweet.fields=entities | Array of objects | -| twitter_entities.urls.indices\[0\] | data.entities.urls.start | tweet.fields=entities | Int | -| twitter_entities.urls.indices\[1\] | data.entities.urls.end | tweet.fields=entities | Int | -| twitter_entities.urls.url | data.entities.urls.url | tweet.fields=entities | String | -| twitter\_entities.urls.expanded\_url | data.entities.urls.expanded_url | tweet.fields=entities | String | -| twitter\_entities.urls.display\_url | data.entities.urls.display_url | tweet.fields=entities | String | -| Not Available | data.entities.urls.images | tweet.fields=entities | Array of objects | -| Not Available | data.entities.urls.images.url | tweet.fields=entities | String | -| Not Available | data.entities.urls.images.width | tweet.fields=entities | Int | -| Not Available | data.entities.urls.images.height | tweet.fields=entities | Int | -| gnip.urls.expanded_status | data.entities.urls.status | tweet.fields=entities | Int | -| gnip.urls.expanded\_url\_title | data.entities.urls.title | tweet.fields=entities | String | -| gnip.urls.expanded\_url\_description | data.entities.urls.description | tweet.fields=entities | String | -| gnip.urls.expanded_url | data.entities.urls.unwound_url | tweet.fields=entities | String | -| twitter_entities.symbols | data.entities.cashtags | tweet.fields=entities | Array of objects | -| twitter_entities.symbols.indices\[0\] | data.entities.cashtags.start | tweet.fields=entities | Int | -| twitter_entities.symbols.indices\[1\] | data.entities.cashtags.end | tweet.fields=entities | Int | -| twitter_entities.symbols.text | data.entities.cashtags.tag | tweet.fields=entities | String | -| twitter_entities.hashtags | data.entities.hashtags | tweet.fields=entities | Array of objects | -| twitter_entities.hashtags.indices\[0\] | data.entities.hashtags.start | tweet.fields=entities | Int | -| twitter_entities.hashtags.indices\[1\] | data.entities.hashtags.end | tweet.fields=entities | Int | -| twitter_entities.hashtags.text | data.entities.hashtags.tag | tweet.fields=entities | String | -| twitter\_entities.user\_mentions | data.entities.mentions | tweet.fields=entities | Array of objects | -| twitter\_entities.user\_mentions.indices\[0\] | data.entities.mentions.start | tweet.fields=entities | Int | -| twitter\_entities.user\_mentions.indices\[1\] | data.entities.mentions.end | tweet.fields=entities | Int | -| twitter\_entities.user\_mentions.screen_name | data.entities.mentions.tag | tweet.fields=entities | String | -| twitter\_entities.user\_mentions.id_str | data.entities.mentions.id | tweet.fields=entities | String | -| twitter\_entities.user\_mentions.id | Not Available | Not Available | | -| Not Available | data.context_annotations | tweet.fields=context_annotations | Array of objects | -| Not Available | data.context_annotations.domain | tweet.fields=context_annotations | Object | -| Not Available | data.context_annotations.domain.id | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.domain.name | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.domain.description | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.entity | tweet.fields=context_annotations | Object | -| Not Available | data.context_annotations.entity.id | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.entity.name | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.entity.description | tweet.fields=context_annotations | String | -| geo | data.geo | tweet.fields=geo | Object | -| Derived from location.link | data.geo.place_id | tweet.fields=geo | String | -| Not Available | data.public_metrics | tweet.fields=public_metrics | Object | -| favoritesCount | data.public\_metrics.like\_count | tweet.fields=public_metrics | Int | -| retweetCount | data.public\_metrics.retweet\_count | tweet.fields=public_metrics | Int | -| Not Available | data.public\_metrics.quote\_count | tweet.fields=public_metrics | Int | -| Not Available | data.public\_metrics.reply\_count | tweet.fields=public_metrics | Int | -| Not Available | data.non\_non\_public_metrics | tweet.fields=non\_public\_metrics | Object | -| Not Available | data.non\_public\_metrics.impression_count | tweet.fields=non\_public\_metrics | Int | -| Not Available | data.non\_public\_metrics.url\_link\_count | tweet.fields=non\_public\_metrics | Int | -| Not Available | data.non\_public\_metrics.user\_profile\_count | tweet.fields=non\_public\_metrics | Int | -| Not Available | data.organic_metrics | tweet.fields=organic_metrics | Object | -| Not Available | data.organic\_metrics.like\_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.retweet\_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.reply\_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.impression\_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.url\_link_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.user\_profile_count | tweet.fields=organic_metrics | Int | -| Not Available | data.promoted_metrics | tweet.fields=promoted_metrics | Object | -| Not Available | data.promoted\_metrics.like\_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.retweet\_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.reply\_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.impression\_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.url\_link_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.user\_profile_count | tweet.fields=promoted_metrics | Int | -| gnip.profileLocations | Not Available | Not Available | | -| gnip.profileLocations.address | Not Available | Not Available | | -| gnip.profileLocations.address.country | Not Available | Not Available | | -| gnip.profileLocations.address.countryCode | Not Available | Not Available | | -| gnip.profileLocations.displayName | Not Available | Not Available | | -| gnip.profileLocations.geo | Not Available | Not Available | | -| gnip.profileLocations.geo.coordinates | Not Available | Not Available | | -| gnip.profileLocations.geo.type | Not Available | Not Available | | -| gnip.profileLocations.objectType | Not Available | Not Available | | - -#### User object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| actor | includes.users | expansions=author_id | Array of objects | -| Derived from actor.id | includes.users.id | expansions=author_id | String | -| actor.displayName | includes.users.name | expansions=author_id | String | -| actor.preferredUsername | includes.users.username | expansions=author_id | String | -| actor.postedTime | includes.users.created_at | expansions=author\_id&user.fields=created\_at | Date (ISO 8601) | -| actor.summary | includes.users.description | expansions=author_id&user.fields=description | String | -| Not Available | includes.users.pinned\_tweet\_id | expansions=author\_id&user.fields=pinned\_tweet_id | String | -| Not Available | includes.users.protected | expansions=author_id&user.fields=protected | Boolean | -| actor.link | Not Available | Not Available - construct from includes.users.username | | -| actor.twitterTimeZone | Not Available | Not Available - infer from Tweet created_at | | -| actor.utcOffset | Not Available | Not Available - infer from Tweet created_at | | -| actor.favoritesCount | Not Available | Not Available | | -| actor.followersCount | includes.users.public\_metrics.followers\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| actor.friendsCount | includes.users.public\_metrics.following\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| actor.listedCount | includes.users.public\_metrics.listed\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| actor.statusesCount | includes.users.public\_metrics.tweet\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| actor.languages\[\] | Not Available | Not Available -  infer from Tweet  lang | | -| actor.location.displayName | includes.users.location | expansions=author_id&user.fields=location | String | -| actor.image | includes.users.profile\_image\_url | expansions=author\_id&user.fields=profile\_image_url | String | -| actor.links | includes.users.url | expansions=author_id&user.fields=url | String | -| actor.verified | includes.users.verified | expansions=author_id&user.fields=verified | Boolean | -| Not Available | includes.users.withheld | expansions=author_id&user.fields=withheld | Object | -| Not Available | includes.users.entities | expansions=author_id&user.fields=entities | Object | -| Not Available | includes.users.entities.url | expansions=author_id&user.fields=entities | Object | -| actor.links | includes.users.entities.url.urls | expansions=author_id&user.fields=entities | Array of objects | -| Not Available | includes.users.entities.url.urls.start | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.url.urls.end | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.url.urls.url | expansions=author_id&user.fields=entities | String | -| actor.links.href | includes.users.entities.url.urls.expanded_url | expansions=author_id&user.fields=entities | String | -| Not Available | includes.users.entities.url.urls.display_url | expansions=author_id&user.fields=entities | String | -| Not Available | includes.users.entities.description | expansions=author_id&user.fields=entities | Object | -| Not Available | includes.users.entities.description.hashtags | expansions=author_id&user.fields=entities | Array of objects | -| Not Available | includes.users.entities.description.hashtags.start | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.hashtags.end | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.hashtags.tag | expansions=author_id&user.fields=entities | String | -| Not Available | includes.users.entities.description.mentions | expansions=author_id&user.fields=entities | Array of objects | -| Not Available | includes.users.entities.description.mentions.start | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.mentions.end | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.mentions.username | expansions=author_id&user.fields=entities | String | -| Not Available | includes.users.entities.description.cashtags | expansions=author_id&user.fields=entities | Array of objects | -| Not Available | includes.users.entities.description.cashtags.start | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.cashtags.end | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.cashtags.tag | expansions=author_id&user.fields=entities | String | - - -#### Poll object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| Not Available | includes.polls | expansions=attachments.poll_ids | Array of objects | -| Not Available | includes.polls.id | expansions=attachments.poll_ids | String | -| Not Available | includes.polls.options | expansions=attachments.poll_ids | Array of objects | -| Not Available | includes.polls.options.position | expansions=attachments.poll_ids | Int | -| Not Available | includes.polls.options.label | expansions=attachments.poll_ids | String | -| Not Available | includes.polls.options.votes | expansions=attachments.poll_ids | Int | -| Not Available | includes.polls.voting_status | expansions=attachments.poll\_ids&poll.fields=voting\_status | String | -| Not Available | includes.polls.duration_minutes | expansions=attachments.poll\_ids&poll.fields=duration\_minutes | Int | -| Not Available | includes.polls.end_datetime | expansions=attachments.poll\_ids&poll.fields=end\_datetime | Date (ISO 8601) | - -#### Place object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| location | includes.places | expansions=geo.place_id | array of objects | -| location.displayName | includes.places.full_name | expansions=geo.place_id | string | -| Parsed from location.link | includes.places.id | expansions=geo.place_id | string | -| location.name | includes.places.name | expansions=geo.place_id&place.fields=name | string | -| location.country_code | includes.places.country | expansions=geo.place_id&place.fields=country | string | -| location.twitter\_place\_type | includes.places.place_type | expansions=geo.place\_id&place.fields=place\_type | string | -| location.twitter\_country\_code | includes.places.country_code | expansions=geo.place\_id&place.fields=country\_code | string | -| location.geo | includes.places.geo | expansions=geo.place_id&place.fields=geo | object | -| location.geo.type | includes.places.geo.type | expansions=geo.place_id&place.fields=geo | string | -| location.geo.coordinates | includes.places.geo.bbox | expansions=geo.place_id&place.fields=geo | array | -| Not Available | includes.places.geo.properties | expansions=geo.place_id&place.fields=geo | object | - -#### Media object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| twitter_entities.media OR twitter\_extended\_entities.media | includes.media | expansions=attachments.media_keys | Array of objects | -| twitter\_entities.media.id\_str OR twitter\_extended\_entities.media.id_str | includes.media.media_key | expansions=attachments.media_keys | String | -| twitter_entities.media.id OR twitter\_extended\_entities.media.id | Not available | Not available | | -| twitter_entities.media.indices OR twitter\_extended\_entities.media.indices | Not available | Not available | | -| twitter\_entities.media.additional\_media_info OR twitter\_extended\_entities.media.additional\_media\_info | Not available | Not available | | -| twitter\_entities.media.additional\_media_info.monetizable OR twitter\_extended\_entities.media.additional\_media\_info.monetizable | Not available | Not available | | -| twitter\_entities.media.media\_url OR twitter\_extended\_entities.media.media_url | Not available | Not available | | -| twitter\_entities.media.media\_url_https OR twitter\_extended\_entities.media.media\_url\_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | String | -| twitter_entities.media.url OR twitter\_extended\_entities.media.url | Not available | Not available | | -| twitter\_entities.media.display\_url OR twitter\_extended\_entities.media.display_url | Not available | Not available | | -| twitter\_entities.media.expanded\_url OR twitter\_extended\_entities.media.expanded_url | Not available | Not available | | -| twitter_entities.media.type OR twitter\_extended\_entities.media.type | includes.media.type | expansions=attachments.media_keys | String | -| twitter_entities.media.sizes OR twitter\_extended\_entities.media.sizes | Not available | Not available | | -| twitter_entities.media.sizes.thumb OR twitter\_extended\_entities.media.sizes.thumb | Not available | Not available | | -| twitter_entities.media.sizes.thumb.h OR twitter\_extended\_entities.media.sizes.thumb.h | Not available | Not available | | -| twitter_entities.media.sizes.thumb.w OR twitter\_extended\_entities.media.sizes.thumb.w | Not available | Not available | | -| twitter_entities.media.sizes.thumb.resize OR twitter\_extended\_entities.media.sizes.thumb.resize | Not available | Not available | | -| twitter_entities.media.sizes.small OR twitter\_extended\_entities.media.sizes.small | Not available | Not available | | -| twitter_entities.media.sizes.small.h OR twitter\_extended\_entities.media.sizes.small.h | Not available | Not available | | -| twitter_entities.media.sizes.small.w OR twitter\_extended\_entities.media.sizes.small.w | Not available | Not available | | -| twitter_entities.media.sizes.small.resize OR twitter\_extended\_entities.media.sizes.small.resize | Not available | Not available | | -| twitter_entities.media.sizes.medium OR twitter\_extended\_entities.media.sizes.medium | Not available | Not available | | -| twitter_entities.media.sizes.medium.h OR twitter\_extended\_entities.media.sizes.medium.h | Not available | Not available | | -| twitter_entities.media.sizes.medium.w OR twitter\_extended\_entities.media.sizes.medium.w | Not available | Not available | | -| twitter_entities.media.sizes.medium.resize OR twitter\_extended\_entities.media.sizes.medium.resize | Not available | Not available | | -| twitter_entities.media.sizes.large OR twitter\_extended\_entities.media.sizes.large | Not available | Not available | | -| twitter_entities.media.sizes.large.h OR twitter\_extended\_entities.media.sizes.large.h | includes.media.height | expansions=attachments.media_keys&media.fields=height | Int | -| twitter_entities.media.sizes.large.w OR twitter\_extended\_entities.media.sizes.large.w | includes.media.width | expansions=attachments.media_keys&media.fields=width | Int | -| twitter_entities.media.sizes.large.resize OR twitter\_extended\_entities.media.sizes.large.resize | Not available | Not available | | -| twitter\_extended\_entities.media.video_info | Not available | Not available | | -| twitter\_extended\_entities.media.video\_info.aspect\_ratio | Not available | Not available | | -| twitter\_extended\_entities.media.video\_info.duration\_millis | includes.media.duration_ms | expansions=attachments.media\_keys&media.fields=duration\_ms | Int | -| twitter\_extended\_entities.media.video_info.variants | Not available | Not available | | -| twitter\_extended\_entities.media.video_info.variants.bitrate | Not available | Not available | | -| twitter\_extended\_entities.media.video\_info.variants.content\_type | Not available | Not available | | -| twitter\_extended\_entities.media.video_info.variants.url | Not available | Not available | | -| Not available | includes.media.alt_text | expansions=attachments.media\_keys&media.fields=alt\_text | String | -| Not available | includes.media.public_metrics | expansions=attachments.media\_keys&media.fields=public\_metrics | Object | -| Not available | includes.media.public\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=public\_metrics | Int | -| Not available | includes.media.non\_public\_metrics | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Object | -| Not available | includes.media.non\_public\_metrics.playback\_0\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_25\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_50\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_75\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_100\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.organic_metrics | expansions=attachments.media\_keys&media.fields=organic\_metrics | Object | -| Not available | includes.media.organic\_metrics.playback\_0_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_25_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_50_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_75_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_100_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.promoted_metrics | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Object | -| Not available | includes.media.promoted\_metrics.playback\_0_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.playback\_25_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.playback\_50_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.playback\_75_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.playback\_100_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | - -#### Matching rules object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| gnip.matching_rules | matching_rules | Default in filtered stream | Array of objects | -| gnip.matching_rules.tag | matching_rules.tag | Default in filtered stream | String | -| gnip.matching_rules.tag.id | Not Available | Not Available | | -| gnip.matching\_rules.tag.id\_str | matching_rules.id | Default in filtered stream | String | - - -### Visual data format migration tool - -The visual data format migration tool is a web application that displays the fields that map from the [X API v1.1. data format](https://developer.x.com/en/docs/x-api/v1/data-dictionary/overview) to the [X API v2 format](/x-api/fundamentals/data-dictionary) for a given Tweet or user object. Either a Tweet ID or user ID can be provided to the application to see this mapping. - -Please note that you will need to log in with your Twitter account in order to use the app. -
- - diff --git a/enterprise-api/migrate/overview.mdx b/enterprise-api/migrate/overview.mdx deleted file mode 100644 index e319f2380..000000000 --- a/enterprise-api/migrate/overview.mdx +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: Overview -keywords: ["migration", "API migration", "v2 migration", "migrate to v2", "migration guide", "upgrade to v2", "migration overview"] ---- -import { Button } from "/snippets/button.mdx" - -The latest version of the X API v2 is a big deal. As such, we’ve broken this migration section into a few partitions: - -| What’s new with X API v2 | Learn about the new endpoints and functionality that we’ve released to X API v2. | -|:----------------------------- |:------------------------------------------------------------------------------------------------------------------- | -| Ready to migrate? | Get started with your migration with a set of guides and instructions. | -| Data format migration guide | Learn how to rework your data parsers that previously worked with the standard v1.1, and enterprise data formats. | -| X API endpoint map | See how standard v1.1, and enterprise endpoints map to the new X API v2 endpoints. | - ----- -## What is the X API v2? - -The X API v2 is now the primary X API, and is where product investment and innovation are focused. We’ve partnered with developers to build the next generation of the X API to better serve our diverse community of developers. Based on developer feedback, we’ve re-built the API to better serve a broader collection of needs, introduced new features and endpoints, and improved upon the developer experience. - -The X API v2 is now the primary X API, and is where product investment and innovation are focused. Over the past few years, we partnered with developers and re-built the API to better serve a broader collection of needs, introduce new features and endpoints, and improve upon the developer experience. We are committed to continuing to build an open developer platform, and are excited to see what you build with the X API v2. - -## Why migrate? - -The X API v2 is built with a modern and more sustainable foundation and includes both improved replacement endpoints for the standard v1.1, and enterprise products, but also net-new functionality. We strongly encourage customers of legacy APIs (v1.1, and enterprise) to begin to migrate to v2 as we do intend to deprecate them eventually. Use the X API to listen to and analyze the public conversation, engage with people on X, and innovate. - -In this section, we will discuss the endpoints and functionality. - -## V2 endpoints - -You can see a full list of v2 endpoints and their pre-v2 equivalent via the following guide: - - - -While most of the endpoints in X API v2 are replacements, we have introduced several new endpoints. Here are several examples of new endpoints that we’ve released to v2: - -- [Spaces endpoints](/x-api/spaces/introduction) to help people get more out of X Spaces, and to allow developers to help shape the future of audio conversations. -- [Hide replies](/x-api/posts/hide-replies/introduction), which allows you to build tools that help limit the impact of abusive, distracting, or misleading replies at scale. -- New Lists endpoints that allow you to [pin and unpin Lists](/x-api/lists/pinned-lists/introduction), or look up someone’s pinned Lists. -- New [batch compliance endpoints](/x-api/compliance/batch-compliance/introduction) that allow you to ensure your stored user and Tweet data is in compliance. - -## New Functionality - -X API v2 also includes new features that will help you find more value with the X API. A lot of what is new has been driven by your feedback and includes certain features that were reserved for enterprise customers previously. - -Some of the improvements to the API include: - -- [A consistent design across endpoints](/x-api/fundamentals/consistency) -- [The ability to specify which fields and objects return in the response payload](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) -- [New and more detailed data objects](/x-api/fundamentals/data-dictionary) -- [Receive and filter data with new contextual information powered by Tweet annotations](/x-api/fundamentals/post-annotations) -- [Access to new metrics](/x-api/fundamentals/metrics) -- [Easily identify and filter for conversations that belong to a reply thread](/x-api/fundamentals/conversation-id) -- [Advanced functionality and increased access to data for academic researchers](https://developer.x.com/content/developer-twitter/en/products/twitter-api/academic-research) -- [Recovery and redundancy functionality for streaming endpoints](/x-api/posts/filtered-stream/integrate/recovery-and-redundancy-features) -- [Easily return counts of Tweets that match a query](/x-api/posts/counts/introduction) -- [Support for Edit Tweets](/x-api/fundamentals/edit-posts) -- High confidence spam filtering -- Shortened URLs are fully unwound for more effective filtering and analysis -- Simplified JSON response objects by removing deprecated fields and modernizing labels -- Return of 100% of matching public and available Tweets in search queries -- Streaming "rules" so you can make changes without dropping connections -- More expressive query language for search Tweets, Tweet counts, and filtered stream -- OpenAPI spec to build new libraries & more transparently track changes - -### Discover New and Updated Response Objects - -The following six data objects are available with the v2 endpoints: - -| Object | Description | -|:--------|:-------------| -| [Tweet](/x-api/fundamentals/data-dictionary#tweet) | The Tweet object has a long list of root-level fields, such as `id`, `text`, and `created_at`. Tweet objects are also the parent object to several child objects including `user`, `media`, `poll`, and `place`. | -| [User](/x-api/fundamentals/data-dictionary#user) | The user object contains X user account metadata describing the referenced user. | -| [Spaces](/x-api/fundamentals/data-dictionary#space) | The Space object consists of fields such as `state`, `host_id`, `is_ticketed`, and even `lang`. | -| [Lists](/x-api/fundamentals/data-dictionary#list) | The List object contains basic information about the requested list including `description`, `member_count`, and `owner_id`. | -| [Media](/x-api/fundamentals/data-dictionary#media) | If a Tweet contains media (such as images), then the media object can be requested using the `media.fields` parameter and includes fields such as the `media_key`, `type`, `url`, `preview_image_url`, and more. | -| [Poll](/x-api/fundamentals/data-dictionary#poll) | A poll included in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet object. | -| [Place](/x-api/fundamentals/data-dictionary#place) | The place object consists of fields such as `place_id`, `geo` object, `country_code`, and more. This information can be used to identify Tweets and study Tweets by location. | - -Learn more about [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -### Flexibility to Choose Which Objects and Fields You Receive - -When making a request to a GET endpoint, you will receive the primary data object that relates to that endpoint, which will include a set of default fields. For example, the Tweet object delivers the `id` and `text` fields as its default. - -If you would like to retrieve additional fields with your request, you will have to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. The expansions parameter enables you to retrieve related data objects such as a user's pinned Tweet or a media object, while the field operators enable you to request specific fields within returned objects beyond the defaults. - -Here is a full list of expansions that you can request with the different X API v2 endpoints: - -| Object / Resource | Available Expansions | -|:-------------------|:----------------------| -| Tweets | `author_id`, `edit_history_tweet_ids`, `entities.mentions.username`, `in_reply_to_user_id`, `referenced_tweets.id`, `referenced_tweets.id.author_id`, `attachments.poll_ids`, `attachments.media_keys`, `geo.place_id` | -| Users | `pinned_tweet_id` | -| Spaces | `invited_user_ids`, `speaker_ids`, `creator_id`, `host_ids`, `topic_ids` | - -Learn more about [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -## New Metrics Available within Tweets, Users, Spaces, and Media Objects - -More metrics are now accessible within Tweet, user, Spaces, Lists, and media objects. These metrics are both public and private, and some metrics can be broken down into an organic or promoted context for Tweet ads. - -Learn more about the available [metrics](/x-api/fundamentals/metrics). - -| Object | Available Metrics | Public Metrics | Private Metrics | Organic Metrics | Promoted Metrics | -|:---------|:-------------------------|:----------------|:-----------------|:-----------------|:------------------| -| tweets | retweet_count | ✔️ | | ✔️ | ✔️ | -| | quote_count | ✔️ | | | | -| | like_count | ✔️ | | ✔️ | ✔️ | -| | reply_count | ✔️ | | ✔️ | ✔️ | -| | impression_count | | ✔️ | ✔️ | ✔️ | -| | url_profile_clicks | | ✔️ | ✔️ | ✔️ | -| | url_link_clicks | | ✔️ | ✔️ | ✔️ | -| user | follower_count | ✔️ | | | | -| user | following_count | ✔️ | | | | -| media | view_count | | ✔️ | | | -| media | playback_0_count | | ✔️ | | | -| space | participant_count | ✔️ | | | | - -## Edit Tweets - -The X API v2 endpoints provide edited Tweet metadata. The _Edit Tweet_ feature was first introduced for testing among X employees on September 1, 2022. Starting on that date, eligible Tweets are editable for 30 minutes and up to 5 times. Learn more about [Edit Tweets](/x-api/fundamentals/edit-posts). -Using the X API v2, a developer can find out: - -- If a Tweet was edit eligible at the time of creation. Some Tweets, such as those with polls or scheduled Tweets, can not be edited. -- Tweets are editable for 30 minutes, and can be edited up to 5 times. For editable Tweets you can see if time for editing remains and how many more edits are possible. -- If you are viewing an edited version of a Tweet (in most cases the API will return the most recent version of a Tweet, unless a specific past version is requested by Tweet ID). -- The entire edit history of the Tweet. -- The engagement attributed to each version of the Tweet. - -## Track Threaded Conversations - -A new Tweet field helps identify which conversation thread a Tweet belongs to. A conversation ID is the Tweet ID of the Tweet that started the conversation. Learn more about [conversation tracking](/x-api/fundamentals/conversation-id). - -## Ready to migrate - -In order to use v2 endpoints, you will need the following things: - -- [A developer account](https://developer.x.com/en/portal/petition/essential/basic-info) -- [A developer App](https://developer.x.com/en/apps) created within a [Project](resources/fundamentals/projects) -- [Keys and tokens](resources/fundamentals/authentication) from that Project’s developer App - -Please note the importance of using keys and tokens from an App within an App. If you are using keys and tokens from an App outside of a Project, you will not be able to make a request to v2 endpoints. - -Once you have a developer account, you can set up all of the above in the [Developer Console](https://developer.x.com/en/portal/petition/essential/basic-info). - -### Authentication -With the new Twitter API, you’ll use two different authentication patterns, OAuth 1.0a User Context and OAuth 2.0 Bearer Token, to access different endpoints. Each serves a different purpose when making requests to the endpoints: - -OAuth 1.0a User Context is required when making a request on behalf of a Twitter user -OAuth 2.0 Bearer token is required to make requests on behalf of your developer App - -## Tools and Code - -To help you get started and familiarize yourself with the new endpoints and capabilities we have a few options to jump start your work: - -- We have a Twitter [Postman collection](https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80) that allows you to use the Postman client to make requests of and connect to the individual endpoints. This is a low-friction way to test authentication and experiment with the endpoints. -- We’ve also provided a list of both Twitter-supported and third-party libraries in Ruby, Python, Node, Java, and many more. For additional context, take a look at our [tools and libraries page](/tools-and-libraries). - -## Migrating to Updated Endpoints - -As you start to explore the new Twitter v2 endpoints, we’ve built a series of detailed migration guides to help you compare and contrast each updated endpoint's capabilities compared to older versions: - -- **Tweets** - - [Tweets lookup](/x-api/posts/lookup/integrate) - - [Manage Tweets](/x-api/posts/manage-tweets/migrate/overview) - - [Timelines](/x-api/posts/timelines/migrate/overview) - - [Search Tweets](/x-api/posts/search/migrate/overview) - - [Tweet counts](/x-api/posts/counts/migrate/overview) - - [Filtered stream](/x-api/posts/filtered-stream/migrate/overview) - - Sampled stream - - [Retweets](/x-api/posts/retweets/migrate/overview) - - [Likes](/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2) - - [Hide replies](/x-api/posts/hide-replies/migrate) -- **Users** - - [Users lookup](/x-api/users/lookup/migrate/overview) - - [Follows](/x-api/users/follows/migrate/standard-to-twitter-api-v2) - - [Blocks](/x-api/users/blocks/migrate) - - [Mutes](/x-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2) -- **Lists** - - [List lookup](/x-api/lists/list-lookup/migrate/overview) - - [Manage Lists](/x-api/lists/manage-lists/migrate/overview) - - [List Tweet lookup](/x-api/lists/list-tweets/migrate/overview) - - [List members](/x-api/lists/list-members/migrate/overview) - -## Migrating to the New Data Format - -As you move from v1.1 or enterprise to v2, it is important to understand that the format the data is delivered in has changed significantly. We have added new fields, modified the sequence of fields, and in some cases removed elements altogether. - -To learn more about these changes, we are developing a series of guides that will help you map out the pre-v2 data format fields to the newer fields, and describe how to request these new fields. - -You can learn more by visiting our [data formats migration](/x-api/migrate/data-format-migration) section of this migration hub, or by visiting our specific data format guides: - -- [Native format to x API v2 (standard v1.1)](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) -- [Native Enriched to X API v2 (enterprise)](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2) -- [Activity Streams to X API v2 (enterprise)](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) - -## What’s Next? - -Those of you who have used the platform for some time will notice that many of the new endpoints are aligned with existing [standard v1.1](https://developer.x.com/en/docs/twitter-api/v1) and [enterprise](/x-api/enterprise-gnip-2.0/enterprise-gnip) endpoints. Indeed, we intend for these to replace all three versions in the future. - -We’ve put together a table to help you understand how the [X API endpoints map](/x-api/migrate/x-api-endpoint-map) to previous versions. - -If you’d like to see what’s coming next, please visit our [product roadmap](https://trello.com/b/myf7rKwV/twitter-developer-platform-roadmap). - -We also have a [changelog](https://developer.x.com/en/updates/changelog) that you can check out to understand what we have already released. - -### What Should We Build Next? - -As we build out additional capabilities of the X API v2 we want to continue to hear from you. We welcome and encourage [feedback](https://twitterdevfeedback.uservoice.com/) from you. - -Take a look at the ideas that have already been submitted, show your support for those that correlate with your needs, and provide feedback as well! diff --git a/enterprise-api/migrate/ready-to-migrate.mdx b/enterprise-api/migrate/ready-to-migrate.mdx deleted file mode 100644 index e69de29bb..000000000 diff --git a/enterprise-api/migrate/x-api-endpoint-map.mdx b/enterprise-api/migrate/x-api-endpoint-map.mdx deleted file mode 100644 index 651c42c04..000000000 --- a/enterprise-api/migrate/x-api-endpoint-map.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: X API endpoint map -keywords: ["endpoint map", "API endpoint map", "v1.1 to v2", "endpoint mapping", "API mapping", "endpoint comparison"] ---- - -The following table maps the X API v2 endpoints to the corresponding standard v1.1, and enterprise endpoints. To learn more about each of these versions and tiers, please visit our [X API getting started guide](/x-api/getting-started/about-x-api). - -You'll notice that we still have several items marked as **\[Coming Soon]**. If you notice anything within this table that is marked as **\[Replacement Under Consideration]** or **\[No Replacement Planned]**, and you would like to see us release a v2 version of that endpoint, please let us know via our [community forum](https://devcommunity.x.com/) or your enterprise account manager.  - -| | Standard v1.1 | Enterprise | X API v2 | -| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Posts** | GET statuses/show
GET statuses/lookup | | [Posts lookup](/x-api/posts/lookup/introduction) | -| | POST statuses/update
POST statuses/destroy/:id | | [Manage Posts](/x-api/posts/manage-tweets/introduction) | -| | GET statuses/user\_timeline
GET statuses/mentions\_timeline
GET statuses/home\_timeline | | [Timelines](/x-api/posts/timelines/introduction)
- User Post timeline
- User mention timeline
- Reverse chronological home timeline | -| | GET search/tweets | [Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api)
- 30 day
- Full-archive | [Search Tweets](/x-api/posts/search/introduction)
- Recent search
- 30 day \[No Replacement Planned]
- Full-archive search | -| | | [Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api)
- 30 day
- Full-archive | [Tweet counts](/x-api/posts/counts/introduction)
- Recent Tweet counts
- 30 day \[No Replacement Planned]
- Full-archive Tweet counts | -| | GET statuses/filter | [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api) | [Filtered stream](/x-api/posts/filtered-stream/introduction)
- Connect to stream
- Add/delete rules
- Retrieve rules | -| | GET statuses/sample (1%) | [Decahose API](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api)
Firehose API | [Volume stream](/x-api/posts/volume-streams/introduction)
- 1% sampled stream
- 10% decahose stream 
- 100% firehose stream | -| | GET statuses/retweeters/:ids
GET statuses/retweets/:id | | [Retweets lookup](/x-api/posts/retweets/introduction) | -| | | | [Quote Tweets lookup](/x-api/posts/quote-tweets) | -| | POST statuses/retweet/:id
POST statuses/unretweet/:id | | [Manage Retweets](/x-api/posts/retweets/introduction)
- Retweet a Tweet
- Undo a Retweet | -| | GET favorites/list | | [Likes lookup](/x-api/posts/likes/introduction)
- Posts liked by a user
- Users who have liked a Post | -| | POST favorites/create
POST favorites/destroy | | [Manage Likes](/x-api/posts/likes/introduction)
- Like a Post
- Unlike a Post | -| | | | [Hide replies](/x-api/posts/hide-replies/introduction) | -| | GET statuses/oembed | | \[No Replacement Planned] | -| | GET statuses/retweets\_of\_me | | \[No Replacement Planned] | -| **Users** | GET users/show
GET users/lookup | | [Users lookup](/x-api/users/lookup/introduction) | -| | GET users/search | | [Get user/search](/x-api/users/search/introduction) | -| | GET followers/ids
GET followers/list
GET friends/ids
GET friends/list | | [Follows lookup](/x-api/users/follows/introduction) | -| | GET friendships/incoming
GET friendships/lookup
GET friendships/no\_retweets/ids
GET friendships/outgoing
GET friendships/show | | [Connection\_status](/x-api/fundamentals/data-dictionary#user) | -| | GET friendships/create
GET friendships/destroy | | [Manage follows](/x-api/users/follows/introduction)
- Follow a user
- Unfollow a user | -| | POST friendships/update | | \[No Replacement Planned] | -| | GET blocks/ids
GET blocks/list | | [Blocks lookup](/x-api/users/blocks/introduction) | -| | POST blocks/create
POST blocks/destroy | | [Manage blocks](/x-api/users/blocks/introduction)
- Block a user
- Unblock a user | -| | GET mutes/users/ids
GET mutes/users/list | | [Mutes lookup](/x-api/users/mutes/introduction) | -| | POST mutes/users/create
POST mutes/users/destroy | | [Manage mutes](/x-api/users/mutes/introduction)
- Mute a user
- Unmute a user | -| | GET account/verify\_credentials | | \[No Changes Planned] | -| | | | \[No Replacement Planned] | -| | GET saved\_searches/show/:id
GET saved\_searches/list
POST saved\_searches/create
POST saved\_searches/destroy/:id | | \[No Replacement Planned] | -| | POST users/report\_spam | | \[No Replacement Planned] | -| | | [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) | \[Migrating in 2025] | -| **Spaces** | | | [Spaces lookup](/x-api/spaces/lookup/introduction) | -| | | | [Spaces search](/x-api/spaces/search/introduction) | -| | | | [Ticketed user lookup](/x-api/spaces/retrieve-the-list-of-users-who-purchased-a-ticket-to-the-given-space) | -| | | | [Tweets shared in a Space lookup](/x-api/spaces/retrieve-posts-from-a-space) | -| **Direct Messages** | | | [Direct Messages lookup](/x-api/direct-messages/lookup/introduction)
[Manage Direct Messages](/x-api/direct-messages/manage/introduction) | -| **Lists** | GET lists/show | | [Lists lookup](/x-api/lists/list-lookup/introduction) | -| | POST lists/create
POST lists/destroy
POST lists/update | | [Manage Lists](/x-api/lists/manage-lists/introduction) | -| | GET lists/statuses | | [Lists Tweets lookup](/x-api/posts/list-posts-timeline-by-list-id) | -| | GET lists/members
GET lists/memberships
POST lists/members/create
POST lists/members/destroy | | [List members](/x-api/lists/list-members#list-members-lookup) | -| | GET lists/subscribers
GET lists/subscriptions
GET lists/lists
POST lists/subscribers/create
POST lists/subscribers/destroy | | [Lists follows](/x-api/lists/manage-lists/introduction) | -| | GET lists/ownerships | | [Owned Lists lookup](/x-api/lists/list-lookup/introduction) | -| | | | [Pinned Lists](/x-api/lists/pinned-lists) | -| | GET lists/members/show
GET lists/subscribers/show | | \[No Replacement Planned] | -| | POST lists/members/create\_all
POST lists/members/destroy\_all | | \[No Replacement Planned] | -| **Media** | | | [Media Upload](https://docs.x.com/x-api/media/introduction) | -| **Trends** | | | [Trends v2](/x-api/trends/introduction) | -| **Geo** | | | \[No Replacement Planned] | -| **Collections** | GET collections/entries
GET collections/list
GET collections/show
POST collections/create
POST collections/destroy
POST collections/entries/add
POST collections/entries/curate
POST collections/entries/move
POST collections/entries/remove
POST collections/update | | \[No Replacement Planned] | -| **Metrics** | | [Engagement API](/enterprise-gnip-2.0/fundamentals/engagement-api)
- /totals
- /28hr
- /historical | /totals - [data is built into v2 responses](/x-api/fundamentals/metrics)
/28hr - \[[Here](https://docs.x.com/x-api/posts/get-last-28hr-metrics-for-posts#get-last-28hr-metrics-for-posts)]
/historical - \[[Here](https://docs.x.com/x-api/posts/get-historical-metrics-for-posts)] | -| **Compliance** | | | [Batch compliance](/x-api/compliance/batch-compliance/introduction) | -| | | [Compliance firehose](/x-api/enterprise-gnip-2.0/fundamentals/firehouse) | [Compliance streams](/x-api/compliance/streams/introduction) | -| **Utilities** | | [Usage API](/x-api/enterprise-gnip-2.0/fundamentals/usage) | [Usage API](/x-api/usage/introduction) | -| | GET application/rate\_limit\_status | | \[No Replacement Planned] | -| | GET help/languages | | \[No Replacement Planned] | -| **Authentication** | | | \[No Changes Planned] | -| **Streaming Likes** | | [Streaming Likes](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#streaming-likes) | \[Coming Soon] | \ No newline at end of file diff --git a/enterprise-api/news/get-news-stories-by-id.mdx b/enterprise-api/news/get-news-stories-by-id.mdx index 9b814921a..dd9503dd2 100644 --- a/enterprise-api/news/get-news-stories-by-id.mdx +++ b/enterprise-api/news/get-news-stories-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/news/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/news/introduction.mdx b/enterprise-api/news/introduction.mdx index 91205659a..7415a0516 100644 --- a/enterprise-api/news/introduction.mdx +++ b/enterprise-api/news/introduction.mdx @@ -2,7 +2,8 @@ title: Introduction sidebarTitle: Introduction keywords: ["news", "news API", "headlines", "breaking news", "news lookup", "news stories", "news search"] ---- + +description: The news lookup endpoint allows developers to get news and headlines breaking on X. This endpoint supports app-auth and user-auth authentication for OAu...--- The news lookup endpoint allows developers to get news and headlines breaking on X. diff --git a/enterprise-api/news/search-news.mdx b/enterprise-api/news/search-news.mdx index c8538ccc9..6f238e0ba 100644 --- a/enterprise-api/news/search-news.mdx +++ b/enterprise-api/news/search-news.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/news/search ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/bookmarks/integrate.mdx b/enterprise-api/posts/bookmarks/integrate.mdx index a0edea0e6..914fc12c1 100644 --- a/enterprise-api/posts/bookmarks/integrate.mdx +++ b/enterprise-api/posts/bookmarks/integrate.mdx @@ -2,8 +2,9 @@ title: Integration guide sidebarTitle: Integration guide keywords: ["bookmarks integration", "bookmarks guide", "bookmarks integration guide", "bookmarks implementation", "bookmarks setup"] ---- + +--- import { Button } from '/snippets/button.mdx'; This page contains information on several tools and critical concepts that you should know as you integrate the manage Bookmarks endpoints into your system. We've broken the page into a couple of different sections: @@ -36,92 +37,4 @@ Take advantage of one of our communities' [third-party libraries](/tools-and-lib All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. -These specific endpoints require the use of [OAuth 2.0 Authorization Code Flow with PKCE](/resources/fundamentals/authentication/oauth-2-0/authorization-code), which means that you must use a set of keys and user Access Tokens to make a successful request. The Access Tokens must be associated with the user that you are requesting on behalf of. If you want to generate a set of Access Tokens for another user, they must authorize or authenticate your App using an [Authorize URL](/resources/fundamentals/authentication#authorize-url). - -Please note that OAuth 2.0 can be tricky to use. If you are not familiar with this authentication method, we recommend using a [library](/tools-and-libraries) or a tool like Postman to properly authenticate your requests. - -#### Developer Console, Projects, and developer Apps - -To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must have a [developer account](/resources/fundamentals/developer-portal), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. - -#### Rate limits - -Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/resources/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. - -These endpoints are rate limited at the user level, meaning that the authenticated user that you are making the request on behalf of can only call the endpoint a certain number of times across any developer App. There is a user rate limit of 180 requests per 15 min window for the GET method. With the GET method of the Bookmarks lookup endpoint you will get back 800 of your most recent Bookmarked Posts. Additionally, there is a user rate limit of 50 requests per 15 minutes for the POST and DELETE methods. - ---- - -### Code examples - -#### Get bookmarks - - - -```bash cURL -curl "https://api.x.com/2/users/123/bookmarks?tweet.fields=created_at,public_metrics" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Get user's bookmarks -for page in client.bookmarks.get(user_id="123", tweet_fields=["created_at", "public_metrics"]): - for post in page.data: - print(f"{post.text} - Likes: {post.public_metrics.like_count}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -// Get user's bookmarks -const paginator = client.bookmarks.get("123", { - tweetFields: ["created_at", "public_metrics"], -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`${post.text} - Likes: ${post.public_metrics?.like_count}`); - }); -} -``` - - - -#### Create a bookmark - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123/bookmarks" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"tweet_id": "1234567890"}' -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Bookmark a Post -response = client.bookmarks.create(user_id="123", tweet_id="1234567890") -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -// Bookmark a Post -const response = await client.bookmarks.create("123", { tweetId: "1234567890" }); -console.log(response.data); -``` - - +These specific endpoints require the \ No newline at end of file diff --git a/enterprise-api/posts/counts/integrate/build-a-query.mdx b/enterprise-api/posts/counts/integrate/build-a-query.mdx index 0f4f7d5ba..386ff9a81 100644 --- a/enterprise-api/posts/counts/integrate/build-a-query.mdx +++ b/enterprise-api/posts/counts/integrate/build-a-query.mdx @@ -2,7 +2,8 @@ title: Build a query sidebarTitle: Build a query keywords: ["build query counts", "counts query", "query builder counts", "counts query syntax", "build counts query"] ---- + +description: **Query limitations! ** Your queries will be limited depending on which [access level](/x-api/getting-started/about-x-api) you are using.--- #### Building a query @@ -186,92 +187,4 @@ https://api.x.com/2/tweets/counts/recent?query=-is%3Aretweet%20has%3Ageo%20(from **Reviewing the sentiment of a conversation** -The next rule could be used to better understand the sentiment of the conversation developing around the hashtag, _#nowplaying_, but scoped to just Posts published within North America. - -Here is what the two different queries, one for positive and one for negative, would look like without the HTTP encoding: - -#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place\_country:US OR place\_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing - -#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place\_country:US OR place\_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible - - -And here is what the query would look like with the HTTP encoding, the query parameter, and the recent Post counts URI: - -https://api.x.com/2/tweets/counts/recent?query=%23nowplaying%20(happy%20OR%20exciting%20OR%20excited%20OR%20favorite%20OR%20fav%20OR%20amazing%20OR%20lovely%20OR%20incredible)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-horrible%20-worst%20-sucks%20-bad%20-disappointing - -https://api.x.com/2/tweets/counts/recent?query=%23nowplaying%20(horrible%20OR%20worst%20OR%20sucks%20OR%20bad%20OR%20disappointing)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-happy%20-exciting%20-excited%20-favorite%20-fav%20-amazing%20-lovely%20-incredible - -**Find Posts that relate to a specific Post annotation** - -This rule was built to filter for original Posts that included an image of a pet that is not a cat, where the language identified in the Post is Japanese. To do this, we used the context: operator to take advantage of the[Post annotation](/x-api/fundamentals/post-annotations) functionality. We first used the[Post lookup](/x-api/posts/lookup/introduction) endpoint and the tweet.fields=context_annotations fields parameter to identify which domain.entity IDs we need to use in our query: - -* Posts that relate to cats return **domain** 66 (Interests and Hobbies category) with entity 852262932607926273 (Cats).  -* Posts that relate to pets return **domain** 65 (Interests and Hobbies Vertical) with entity 852262932607926273 (Pets).  - - -Here is what the query would look like without the HTTP encoding: - -context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja - - -And here is what the query would look like with the HTTP encoding, the query parameter, and the recent Post counts URI: - -https://api.x.com/2/tweets/counts/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja - -#### Operators - -| Operator | Type | Availability | Description | -|:------------------------|:--------------|:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `keyword` | Standalone | Core | Matches a keyword within the body of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body. Tokenization splits words based on punctuation, symbols, and Unicode basic plane separator characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your query. To match strings containing punctuation (for example coca-cola), symbol, or separator characters, you must wrap your keyword in double-quotes. Example: `pepsi OR cola OR "coca cola"` | -| `emoji` | Standalone | Core | Matches an emoji within the body of a Post. Similar to a keyword, emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body. Note that if an emoji has a variant, you must wrap it in double quotes to add to a query. Example: `(😃 OR 😡) 😬` | -| `"exact phrase match"` | Standalone | Core | Matches the exact phrase within the body of a Post. Example: `("X API" OR #v2) -"recent counts"` | -| `#` | Standalone | Core | Matches any Post containing a recognized hashtag, if the hashtag is a recognized entity in a Post. This operator performs an exact match, NOT a tokenized match, meaning the rule `#thanku` will match posts with the exact hashtag #thanku, but not those with the hashtag #thankunext. Example: `#thankunext #fanart OR @arianagrande` | -| `@` | Standalone | Core | Matches any Post that mentions the given username, if the username is a recognized entity (including the @ character). Example: `(@XDevelopers OR @API) -@X` | -| `$` | Standalone | Advanced | Matches any Post that contains the specified ‘cashtag’ (where the leading character of the token is the ‘$’ character). Note that the cashtag operator relies on X's ‘symbols’ entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself. Example: `$twtr OR @XDevelopers -$fb` | -| `from:` | Standalone | Core | Matches any Post from a specific user. The value can be either the username (excluding the @ character) or the user’s numeric user ID. You can only pass a single username/ID per `from:` operator. Example: `from:XDevelopers OR from:API -from:X` | -| `to:` | Standalone | Core | Matches any Post that is in reply to a particular user. The value can be either the username (excluding the @ character) or the user’s numeric user ID. You can only pass a single username/ID per `to:` operator. Example: `to:XDevelopers OR to:API -to:X` | -| `url:` | Standalone | Core | Performs a tokenized match on any validly-formatted URL of a Post. This operator can matches on the contents of both the `url` or `expanded_url` fields. For example, a Post containing "You should check out X Developer Labs: https://t.co/c0A36SWil4" (with the short URL redirecting to https://developer.x.com) will match both the following rules: `from:XDevelopers url:"https://developer.x.com"` and `from:XDevelopers url:"https://t.co"`. Tokens and phrases containing punctuation or special characters should be double-quoted. | -| `retweets_of:` | Standalone | Core | Matches Posts that are Retweets of the specified user. The value can be either the username (excluding the @ character) or the user’s numeric user ID. You can only pass a single username/ID per `retweets_of:` operator. Example: `retweets_of:XDevelopers OR retweets_of:API` | -| `context:` | Standalone | Core | Matches Posts with a specific domain id/entity id pair. You can only pass a single domain/entity per `context:` operator. Example: `context:domain_id.entity_id`. You can combine multiple domain/entities using the OR operator: `(context:47.113922 9372198469633 OR context:11.1088514520308342784)` | -| `entity:` | Standalone | Core | Matches Posts with a specific entity string value. You can only pass a single `entity:` operator. Example: `entity:"string declaration of entity/place"`. Please note that this is only available with recent search. | -| `conversation_id:` | Standalone | Core | Matches Posts that share a common conversation ID. A conversation ID is set to the Post ID of a Post that started a conversation. As Replies to a Post are posted, even Replies to Replies, the `conversation_id` is added to its JSON payload. You can only pass a single conversation ID per `conversation_id:` operator. Example: `conversation_id:1334987486343299072 (from:XDevelopers OR from:API)` | -| `list:` | Standalone | Advanced | Matches Posts posted by users who are members of a specified list. For example, if @XDevelopers and @API were members of List 123, and you included `list:123` in your query, your response will only contain Posts that have been published by those accounts. You can find List IDs by using the List lookup endpoint. Example: `list:123` | -| `place:` | Standalone | Advanced | Matches Posts tagged with the specified location or X place ID. Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes. You can only pass a single place per `place:` operator. Note: See the GET geo/search standard v1.1 endpoint for how to obtain X place IDs. Example: `place:"new york city" OR place:seattle OR place:fd70c22040963ac7` | -| `place_country:` | Standalone | Advanced | Matches Posts where the country code associated with a tagged place/location matches the given ISO alpha-2 character code. You can find a list of valid ISO codes on Wikipedia. You can only pass a single ISO code per `place_country:` operator. Example: `place_country:US OR place_country:MX OR place_country:CA` | -| `point_radius:` | Standalone | Advanced | Matches against the `place.geo.coordinates` object of the Post when present, and in X, against a place geo polygon, where the Place polygon is fully contained within the defined region. `point_radius:[longitude latitude radius]`. Units of radius supported are miles (mi) and kilometers (km). Radius must be less than 25mi. Longitude is in the range of ±180. Latitude is in the range of ±90. All coordinates are in decimal degrees. Rule arguments are contained within brackets, space delimited. Example: `point_radius:[2.355128 48.861118 16km] OR point_radius:[-41.287336 174.761070 20mi]` | -| `bounding_box:` | Standalone | Advanced | Matches against the place.geo.coordinates object of the Post when present, and in X, against a place geo polygon, where the place polygon is fully contained within the defined region. `bounding_box:[west_long south_lat east_long north_lat]`. Width and height of the bounding box must be less than 25mi. Longitude is in the range of ±180. Latitude is in the range of ±90. All coordinates are in decimal degrees. Rule arguments are contained within brackets, space delimited. Example: `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` | -| `is:retweet` | Conjunction required | Core | Matches on Retweets that match the rest of the specified rule. This operator looks only for true Retweets (for example, those generated using the Retweet button). Quote Tweets will not be matched by this operator. Example: `data @XDevelopers -is:retweet` | -| `is:reply` | Conjunction required | Core | Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a query from delivery. Note: This operator is also available with the filtered stream endpoint. When used with filtered stream, this operator matches on replies to an original Post, replies in quoted Posts, and replies in Retweets. Example: `from:XDevelopers is:reply` | -| `is:quote` | Conjunction required | Core | Returns all Quote Tweets, also known as Posts with comments. Example: `"sentiment analysis" is:quote` | -| `is:verified` | Conjunction required | Core | Deliver only Posts whose authors are verified by X. Example: `#nowplaying is:verified` | -| `-is :nullcast` | Conjunction required | Advanced | Removes Posts created for promotion only on ads.x.com that have a `"source":"Twitter for Advertisers (legacy)"` or `"source":"Twitter for Advertisers"`. This operator must be negated. For more info on Nullcasted Posts, see our page on Post availability. Example: `"mobile games" -is:nullcast` | -| `has:hashtags` | Conjunction required | Core | Matches Posts that contain at least one hashtag. Example: `from:XDevelopers -has:hashtags` | -| `has:cashtags` | Conjunction required | Advanced | Matches Posts that contain a cashtag symbol (with a leading ‘$’ character. For example, `$tag`). Example: `#stonks has:cashtags` | -| `has:links` | Conjunction required | Core | This operator matches Posts which contain links and media in the Post body. Example: `from:XDevelopers announcement has:links` | -| `has:mentions` | Conjunction required | Core | Matches Posts that mention another X user. Example: `#nowplaying has:mentions` | -| `has:media` | Conjunction required | Core | Matches Posts that contain a media object, such as a photo, GIF, or video, as determined by X. This will not match on media created with Periscope, or Posts with links to other media hosting sites. Example: `(kittens OR puppies) has:media` | -| `has:images` | Conjunction required | Core | Matches Posts that contain a recognized URL to an image. Example: `#meme has:images` | -| `has:videos` | Conjunction required | Core | Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Periscope, or Posts with links to other video hosting sites. Example: `#icebucketchallenge has:videos` | -| `has:geo` | Conjunction required | Advanced | Matches Posts that have Post-specific geolocation data provided by the X user. This can be either a location in the form of a X place, with the corresponding display name, geo polygon, and other fields, or in rare cases, a geo lat-long coordinate. Note: Operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. Example: `recommend #paris has:geo -bakery` | -| `lang:` | Conjunction required | Core | Matches Posts that have been classified by X as being of a particular language (if, and only if, the Post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results. You can only pass a single BCP 47 language identifier per `lang:` operator. Note: if no language classification can be made the provided result is ‘und’ (for undefined). Example: `recommend #paris lang:en` | - -| | | | | -| :--- | :--- | :--- | :--- | -| Amharic: **am** | German: **de** | Malayalam: **ml** | Slovak: **sk** | -| Arabic: **ar** | Greek: **el** | Maldivian: **dv** | Slovenian: **sl** | -| Armenian: **hy** | Gujarati: **gu** | Marathi: **mr** | Sorani Kurdish: **ckb** | -| Basque: **eu** | Haitian Creole: **ht** | Nepali: **ne** | Spanish: **es** | -| Bengali: **bn** | Hebrew: **iw** | Norwegian: **no** | Swedish: **sv** | -| Bosnian: **bs** | Hindi: **hi** | Oriya: **or** | Tagalog: **tl** | -| Bulgarian: **bg** | Latinized Hindi: **hi-Latn** | Panjabi: **pa** | Tamil: **ta** | -| Burmese: **my** | Hungarian: **hu** | Pashto: **ps** | Telugu: **te** | -| Croatian: **hr** | Icelandic: **is** | Persian: **fa** | Thai: **th** | -| Catalan: **ca** | Indonesian: **in** | Polish: **pl** | Tibetan: **bo** | -| Czech: **cs** | Italian: **it** | Portuguese: **pt** | Traditional Chinese: **zh-TW** | -| Danish: **da** | Japanese: **ja** | Romanian: **ro** | Turkish: **tr** | -| Dutch: **nl** | Kannada: **kn** | Russian: **ru** | Ukrainian: **uk** | -| English: **en** | Khmer: **km** | Serbian: **sr** | Urdu: **ur** | -| Estonian: **et** | Korean: **ko** | Simplified Chinese: **zh-CN** | Uyghur: **ug** | -| Finnish: **fi** | Lao: **lo** | Sindhi: **sd** | Vietnamese: **vi** | -| French: **fr** | Latvian: **lv** | Sinhala: **si** | Welsh: **cy** | -| Georgian: **ka** | Lithuanian: **lt** | | +The next rule could be used to better understand the sentiment of the conversation developing around the hashtag, _#nowplaying_, but scoped to just Posts published within \ No newline at end of file diff --git a/enterprise-api/posts/counts/integrate/overview.mdx b/enterprise-api/posts/counts/integrate/overview.mdx index 2c668d0f3..4d0e2d495 100644 --- a/enterprise-api/posts/counts/integrate/overview.mdx +++ b/enterprise-api/posts/counts/integrate/overview.mdx @@ -6,8 +6,6 @@ keywords: ["post counts integration", "tweet counts integration", "counts overvi This page covers tools and key concepts for integrating the Post counts endpoints. ---- - ## Helpful tools Before we start to explore some key concepts, we recommend that you use one of the following tools or code samples to start testing the functionality of these endpoints. diff --git a/enterprise-api/posts/counts/migrate/enterprise-to-twitter-api-v2.mdx b/enterprise-api/posts/counts/migrate/enterprise-to-twitter-api-v2.mdx index 75b647fea..fab75181c 100644 --- a/enterprise-api/posts/counts/migrate/enterprise-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/counts/migrate/enterprise-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 (Enterprise) sidebarTitle: v1 to v2 (Enterprise) keywords: ["enterprise to v2 counts", "enterprise counts migration", "GNIP to v2 counts", "enterprise counts migration", "migrate enterprise counts"] ---- + +--- ### Enterprise compared to X API v2 **Similarities** @@ -54,78 +55,4 @@ As noted in the pagination section, you can navigate different pages of data usi * 30 day - `http://gnip-api.x.com/search/30day/accounts/:account_name/:label/counts.json` * Full-archive - `http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label/counts.json` * X API v2 endpoints - * Recent (7 day) - `https://api.x.com/2/tweets/counts/recent` - * Full-archive - `https://api.x.com/2/tweets/counts/all` - -**App and Project requirement** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. -  - -**Available time periods** - -Both the enterprise API and X API v2 offer endpoints that allow you to retrieve Post volume data for the full-archive of Posts. - -However, the X API v2 does not offer a 30 day time period endpoint like the enterprise API does. Instead it offers the aforementioned full-archive, or a 7 day time period, which align with the [v2 Search Posts endpoints](/x-api/posts/search/introduction). -  - -**Response data format** - -There are some slight differences in the data format that you will receive via enterprise and X API v2: - -* Enterprise’s counts data is located within a `results` object, while the v2 counts data is located within a data object. -* Enterprise’s counts fields are called `timePeriod` (start time) and `count`, while v2 breaks out the time period into a `start` and `end` field (which use a different date/time format from enterprise explained in request time formats), and renamed the count field to `tweet_count`. -* The enterprise metadata includes `totalCount`, `next`, and the `requestParameters` object at the root level. Instead,v2 doesn’t include the requestParameters object, and moves/renames the following into a `meta` object that lives at the root level: `total_tweet_count` & `next_token`. -   - -**HTTP methods** - -The enterprise version of the API allows you to pass the request as either a POST HTTP method with a JSON body, or a GET HTTP method with a query string. - -V2 only allows you to use the GET HTTP method with a query string. -  - -**Request time formats** - -The enterprise version of this endpoint uses the following date/time format in both the pagination parameters and the `timePeriod` response field: `YYYYMMDDHHmm` - -The v2 endpoint uses ISO 8601/RFC 3339 date/time format in both the pagination parameters and the `start` and `end` response fields: `YYYY-MM-DDTHH:mm:ssZ` - -**Request parameters** - -The following is a table of the request parameters for enterprise and X API v2: - -| Enterprise | Search Posts v2 | -| :--- | :--- | -| query | query | -| bucket | granularity | -| fromDate (YYMMDDHHmm) | start_time (YYYY-MM-DDTHH:mm:ssZ) | -| toDate (YYMMDDHHmm) | end_time (YYYY-MM-DDTHH:mm:ssZ) | -| | since_id | -| | until_id | -| next | next\_token and pagination\_token | - -**Filtering operators** - -While the operators between enterprise and X API v2 are mostly the same, there are some differences in operator availability and some new operators that were introduced to just the X API v2 version. - -To see a full table of the operators that are available for X API v2, enterprise, and even premium, please visit the [Post counts migration landing page](/x-api/posts/counts/migrate/overview). - - -## API reference index - -For a complete API reference, please select an endpoint from below. - -### Recent Post counts - -| | | -| :--- | :--- | -| **Receive a count of Posts that match a query in the last 7 days** | `[GET /2/tweets/counts/recent](/x-api/posts/tweet-counts#api-reference-index/get-tweets-counts-recent)` | - -### Full-archive Post counts - -Only available to those with [Self-serve and Enterprise access](/x-api/getting-started/about-x-api) - -| | | -| :--- | :--- | -| **Receive a count of Posts that match a query** | `[GET /2/tweets/counts/all](/x-api/posts/tweet-counts#api-reference-index/get-tweets-counts-all)` | + * \ No newline at end of file diff --git a/enterprise-api/posts/create-or-edit-post.mdx b/enterprise-api/posts/create-or-edit-post.mdx index 7c8307b1c..ae1997978 100644 --- a/enterprise-api/posts/create-or-edit-post.mdx +++ b/enterprise-api/posts/create-or-edit-post.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/create-post.mdx b/enterprise-api/posts/create-post.mdx index 7c8307b1c..ae1997978 100644 --- a/enterprise-api/posts/create-post.mdx +++ b/enterprise-api/posts/create-post.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/delete-post.mdx b/enterprise-api/posts/delete-post.mdx index 0adba30c3..5521c46cf 100644 --- a/enterprise-api/posts/delete-post.mdx +++ b/enterprise-api/posts/delete-post.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/tweets/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/filtered-stream/integrate/matching-returned-tweets.mdx b/enterprise-api/posts/filtered-stream/integrate/matching-returned-tweets.mdx index 82b5a2c79..94c80142e 100644 --- a/enterprise-api/posts/filtered-stream/integrate/matching-returned-tweets.mdx +++ b/enterprise-api/posts/filtered-stream/integrate/matching-returned-tweets.mdx @@ -2,7 +2,8 @@ title: Matching Posts to Rules sidebarTitle: Matching Posts to Rules keywords: ["matching rules", "filter rules", "rule matching", "stream rules", "filtered stream rules", "rule tags"] ---- + +description: The filtered stream endpoint gives you the ability to have multiple rules in place through a single connection. Before you start receiving Posts in your...--- ### Matching returned Posts to their associated rule diff --git a/enterprise-api/posts/filtered-stream/migrate/overview.mdx b/enterprise-api/posts/filtered-stream/migrate/overview.mdx index 3586f5714..ade7b4461 100644 --- a/enterprise-api/posts/filtered-stream/migrate/overview.mdx +++ b/enterprise-api/posts/filtered-stream/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["filtered stream migration", "stream migration", "v1.1 to v2 filtered stream", "filtered stream migration guide", "migrate filtered stream"] ---- + ## Comparing X API's filtered stream endpoints diff --git a/enterprise-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.mdx b/enterprise-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.mdx index 8dab85301..e8424bb28 100644 --- a/enterprise-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 (Enterprise) sidebarTitle: v1 to v2 (Enterprise) keywords: ["PowerTrack migration", "enterprise to v2 filtered stream", "PowerTrack to v2", "enterprise stream migration", "migrate PowerTrack", "v1 to v2 enterprise stream"] ---- + +--- ### PowerTrack API migration to X API v2 filtered stream Use this migration guide to understand the similarities and differences between [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api) and X API v2 [filtered stream](/x-api/posts/filtered-stream), and to help migrate a current PowerTrack API integration to v2 filtered stream. @@ -36,141 +37,4 @@ Both PowerTrack and X API v2 filtered stream use streaming data delivery, which **Integration process** -Integrating with filtered stream is similar to integrating with PowerTrack, using the general process below: - -1. Establish a streaming connection. -2. Asynchronously send separate requests to add and delete rules from the stream. -3. Reconnect to the stream automatically when connection is disconnected. - -**Persistent stream connection with separate rules management endpoints** - -Similar to the PowerTrack API and Rules API, the new X API v2 filtered stream endpoints allows you to apply multiple rules to a single stream and add and remove rules to your stream while maintaining the stream connection. - -| | | | -| :--- | :--- | :--- | -| **Feature** | **PowerTrack API** | **X API v2 filtered stream** | -| **Connection endpoint** | GET /stream | [GET /2/tweets/search/stream](/x-api/stream/stream-filtered-posts) | -| **Add rules** | POST /rules | [POST /2/tweets/search/stream/rules](/x-api/stream/update-stream-rules) | -| **Get rules** | GET /rules | [GET /2/tweets/search/stream/rules](/x-api/stream/get-stream-rules) | -| **Delete rules** | POST /rules_method=delete | [POST /2/tweets/search/stream/rules](/x-api/stream/update-stream-rules) | - -**Rule syntax, operators, and matching rules logic** - -The X API v2 filtered stream uses a subset of the same rule operators currently used for PowerTrack rules. These operators are used to create boolean based rule syntax used for filtering desired matching Posts from the live stream.  Both PowerTrack and filtered stream use the same rule syntax for building rules and matching logic is the same. While the majority of the operators are available for both PowerTrack and filter stream, there are a few notable differences and net new operators listed below.  For more details and example uses for each operator see current [PowerTrack operators](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-operators) and current X API v2 [filtered stream operators](/x-api/posts/filtered-stream/integrate/operators).  - -Please note that many operators (noted as 'advanced operators') are reserved for those users who have been approved for [Academic Research access or Enterprise access](/x-api/getting-started/about-x-api). - -Operators available with both PowerTrack and X API v2 Filtered stream: - -| **Standalone operators** | **Conjunction required operators (must be used with at least one standalone operator within a rule)** | -| :--- | :--- | -| keyword (example: coffee )

emoji (example: 🐶 or \\uD83D\\uDC36 )

"exact phrase match" (example: "happy birthday" )

from:

to:

@

retweets_of:

#

url: | has:links

lang:

has:mentions

has:media

has:images

has:videos

is:retweet

is:quote

is:verified

has:hashtags

has:geo

sample:

-is:nullcast | - -| | -| :--- | -| **Net new operators available with X API v2 filtered stream** | -| conversation_id: \- matches on Posts that exist in any reply threads from the specified Post conversation root.Net new operators available with X API v2 filtered stream:

context: \- matches on Posts that have been annotated with a context of interest. 

entity: \- matches on Posts that have been annotated with an entity of interest. | - -| | -| :--- | -| **Operators currently only available on PowerTrack API** | -| url_title:

url_description:

followers_count:

statuses_count:

friends_count:

listed_count:

"proximity match"~3

contains:

has:symbols

url_contains:

in\_reply\_to\_status\_id:

retweets\_of\_status_id:

source:

bio:

bio_name:

bio_location:

place:

place_country:

point_radius:

bounding_box:

is:reply

(Available without conjunction)

has:links

lang:

has:mentions

has:media

has:images

has:videos

is:retweet

is:quote

is:verified

is:reply

has:hashtags

has:geo

sample: | - -**Support for Post edit history and metadata** - -Both versions provide metadata that describes any edit history. Check out the [filtered stream API References](/x-api/posts/filtered-stream/introduction) and the [Edit Posts fundamentals page](/x-api/fundamentals/edit-posts) for more details.  - -#### Differences - -**Rule length** - -Rule length is measured the same way (by character count) for both PowerTrack and filtered stream rules, however the maximum length for PowerTrack rules is 2048 characters and the maximum rule length for rules on X API v2 filtered stream varies by [access level](/x-api/getting-started/about-x-api).  - -Enterprise access -  2048 characters (please contact your designated account manager regarding your specific account) - -**Rule volume** - -The PowerTrack maximum rule volume per stream is defined within the enterprise account contract.  X API v2 filtered stream rule volume varies by [access level](/x-api/getting-started/about-x-api). - -Enterprise access - 25000+ rules (please contact your designated account manager regarding your specific account) -  - -**Endpoint URLs** - -* PowerTrack endpoints: - * https://gnip-stream.x.com/stream/powertrack/accounts/{account\_name}/publishers/twitter/{stream\_label}.json - * https://gnip-api.x.com/rules/powertrack/accounts/{account\_name}/publishers/twitter/{stream\_label}.json - * https://gnip-api.x.com/rules/powertrack/accounts/{account\_name}/publishers/twitter/{stream\_label}/validation.json -* X API v2 endpoint: - * https://api.x.com/2/tweets/search/stream - * https://api.x.com/2/tweets/search/stream/rule - -**App and Project requirements for v2 access** - -PowerTrack access is granted through a contracted annual subscription for data, and set up through console.gnip.com by your account manager at X.  PowerTrack does not require a X developer App to access.  In order to use the X API v2 filter stream, you must have [signed up for a X developer account](https://developer.x.com/en/portal/petition/essential/basic-info), and a X [developer App](https://developer.x.com/en/portal/projects-and-apps.html) associated with an App. The developer App and Project setup for X API v2 access is all done through the [Developer Console](https://developer.x.com/en/portal/projects-and-apps).   - -**Authentication method** - -The PowerTrack API endpoints use Basic Authentication set up in console.gnip.com. The X API v2 filtered stream endpoints require a X developer App and an [OAuth 2.0 App Access Token](/resources/fundamentals/authentication#oauth-2-0) (also referred to as Application-only or Bearer Authentication). To make requests to the X API v2 version you must use your specific developer App's Access Token to authenticate your requests. - -In the process of setting up your developer account, developer App and Project, an App Access Token is created and shared within the dev portal user interface, however, you can generate a new one by navigating to your app's “Keys and tokens” page on the [Developer Console](https://developer.x.com/en/portal/projects-and-apps). If you’d like to generate/destroy the App Access Tokens programmatically, see this [OAuth 2.0 App-Only guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -**Usage tracking** - -PowerTrack usage can be retrieved programatically using the Usage API, or can be seen in console.gnip.com on the [usage tab](/x-api/enterprise-gnip-2.0/fundamentals/overview#usage-tab).  Post consumption across all PowerTrack streams is deduplicated each day and volume consumption is defined within the enterprise contract.  - -X API v2 filtered stream usage can be tracked within the Developer Console at the Project level. Post consumption is [set at the Project level](/resources/fundamentals/developer-apps) and is shared across several different X API v2 endpoints, including filtered stream, recent search, user Post timeline and user mention timeline.  With pay-per-use pricing, you pay for the Posts you consume. - -**Multiple streams, redundant conections, backfill and Replay API for recovery** - -There are several recovery and redunancy features available via PowerTrack, some of which are not yet available for X API v2 filtered stream.  For PowerTrack, all [recovery and redundancy features](/x-api/enterprise-gnip-2.0/powertrack-api#recovery-and-redundancy-features) are configured within the enterprise contract. PowerTrack API currently has the flexibility to offer multiple PowerTrack streams (commonly "dev" and "production") with unique rulesets.  Currently, the X API v2 filtered stream is only available with a single stream. - -PowerTrack allows you to connect to have multiple connections to a single stream, generally used for redundant connections to different data centers or clients.  - -If a PowerTrack stream is disconnected breifly, a reconnection can be made using the backfillMinutes parameter to reduce the chance of data loss within five minutes of the disconection. While we have added this functionality to the X API v2 version, it is currently only available with Academic Research access, and has been renamed to backfill_minutes. - -If a PowerTrack stream is disconnected for longer than a 5 minute period, the separate [Replay API](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) can be used to recover data for up to a 2 hour period in the recent 5 day past.  Currently, the X API v2 filtered stream does not have a replay feature. - -**Request parameters and response format** - -One of the biggest differences between PowerTrack API and X API v2 filtered stream is the parameter functionality. - -Using the X API v2 filtered stream, there are several parameters used on the connection request to identify which fields or expanded objects to return in the Post payload.  This is common for all v2 endpoints. By default, only the Post id and text are returned for matching Posts but additional parameters, fields and expansions described below, can be added in order to recieve more detailed data per matching Post.  - -fields: X API v2 endpoints enable you to select which fields are provided in your payload. For example, Post, User, Media, Place, and Poll objects all have a list of fields that can be returned (or not).  - -expansions: Used to expand the complementary objects referenced in Post JSON payloads. For example, all Retweets and Replies reference other Posts. By setting expansions=referenced_tweets.id, these other Post objects are expanded according to the \`tweet.fields\` setting.  Other objects such as users, polls, and media can be expanded. - -https://api.x.com/2/tweets/search/stream?tweet.fields=created\_at,public\_metrics,author\_id,entities&expansions=attachments.poll\_ids - -You can learn more about how to use fields and expansions by visiting our [guide](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions), and by reading through our broader [data dictionary](/x-api/fundamentals/data-dictionary). - -| | | -| :--- | :--- | -| **Connection to PowerTrack ** | **Example request to X API v2 filtered stream** | -| curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/powertrack/accounts/:account\_name/publishers/twitter/:stream\_label.json" | curl "https://api.x.com/2/tweets/search/stream?tweet.fields=attachments,author\_id,context\_annotations,conversation\_id,created\_at,entities,geo,id,in\_reply\_to\_user\_id,lang,possibly\_sensitive,public\_metrics,referenced\_tweets,reply\_settings,source,text,withheld&user.fields=created\_at,description,entities,id,location,name,pinned\_tweet\_id,profile\_image\_url,protected,public\_metrics,url,username,verified,withheld&expansions=author\_id,referenced\_tweets.id,referenced\_tweets.id.author\_id,entities.mentions.username,attachments.poll\_ids,attachments.media\_keys,in\_reply\_to\_user\_id,geo.place\_id&place.fields=contained\_within,country,country\_code,full\_name,geo,id,name,place\_type&poll.fields=duration\_minutes,end\_datetime,id,options,voting\_status" -H "Authorization: Bearer $ACCESS_TOKEN" | - -The PowerTrack API data format is set within console.gnip.com at the stream settings level, which can be set to either the X [native enriched format](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-tweet-object) or [Activity streams format]().  - -PowerTrack API only uses one optional parameter on connection, to reconnect using backfill (backfillMinutes=5). This optional parameter is also available to filtered stream, but is called backfill_minutes, and is only available via Academic Research access. -  - -https://gnip-stream.x.com/stream/powertrack/accounts/{account\_name}/publishers/twitter/{stream\_label}.json?backfillMinutes=5 - -**Response structure and data format** - -As described above, the request parameters set at the connection request for X API v2 filtered stream determine the response data returned.  There are several different response possibilites using different fields and expansions which can range from the most simple default response with only the Post id and text, to an extremely detailed and expanded data payload. - -The data format for PowerTrack is set within console.gnip.com at the stream settings level, which can be set to either the X Native Enriched format or Activity Streams format.  - -The following table references Post response examples in each different format: - -| | | | -| :--- | :--- | :--- | -| **Native enriched format** | **Activity streams format** | **X API v2 filtered stream format** | -| [Payload examples](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-example-payloads) | [Payload examples](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#activity-streams-payload-examples) | [Payload examples](/x-api/fundamentals/data-dictionary#twitter-api-v2-example-payloads) | - -If you would like to know more about how the enterprise data formats map to the X API v2 format, please visit our following guides: - -* [Native Enriched to X API v2 format migration guide](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2) -* [Activity Streams to X API v2 format migration guide](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) +Integrating with filtered stream is similar to integrating with P \ No newline at end of file diff --git a/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx index d417b87c5..33db29d59 100644 --- a/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx @@ -2,6 +2,8 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "filtered stream migration", "migrate filtered stream", "standard to v2 filtered stream", "v1 to v2 filtered stream", "migration guide"] + + --- ### Standard v1.1 compared to X API v2 @@ -129,110 +131,7 @@ X API v2 introduces new operators in support of two new features:  ### Add a rule to filtered stream (v2) - - -```bash cURL -curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \ - -H "Authorization: Bearer $BEARER_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"add": [{"value": "cat has:images", "tag": "cats with images"}]}' -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/search/stream/rules" - -headers = { - "Authorization": f"Bearer {bearer_token}", - "Content-Type": "application/json" -} - -data = { - "add": [{"value": "cat has:images", "tag": "cats with images"}] -} - -response = requests.post(url, headers=headers, json=data) -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Add a rule to filtered stream -response = client.posts.add_stream_rules( - add=[{"value": "cat has:images", "tag": "cats with images"}] -) -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Add a rule to filtered stream -const response = await client.posts.addStreamRules({ - add: [{ value: "cat has:images", tag: "cats with images" }], -}); -console.log(response.data); -``` - - - -### Connect to filtered stream (v2) - - - -```bash cURL -curl "https://api.x.com/2/tweets/search/stream?tweet.fields=created_at,author_id" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/search/stream" - -params = {"tweet.fields": "created_at,author_id"} -headers = {"Authorization": f"Bearer {bearer_token}"} - -# Stream Posts in real-time -response = requests.get(url, headers=headers, params=params, stream=True) -for line in response.iter_lines(): - if line: - print(line.decode("utf-8")) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Connect to filtered stream -for post in client.posts.stream( - tweet_fields=["created_at", "author_id"] -): - print(f"{post.data.created_at}: {post.data.text[:50]}...") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Connect to filtered stream -const stream = client.posts.stream({ - tweetFields: ["created_at", "author_id"], -}); -for await (const post of stream) { - console.log(`${post.data?.created_at}: ${post.data?.text?.slice(0, 50)}...`); -} -``` +**Standard v1.1 vs v2 examples** - +See the full migration examples in the official X API documentation. diff --git a/enterprise-api/posts/get-28-hour-post-insights.mdx b/enterprise-api/posts/get-28-hour-post-insights.mdx index a623f2727..66673bb15 100644 --- a/enterprise-api/posts/get-28-hour-post-insights.mdx +++ b/enterprise-api/posts/get-28-hour-post-insights.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/insights/28hr ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-count-of-all-posts.mdx b/enterprise-api/posts/get-count-of-all-posts.mdx index 42cd08fc1..0fb250883 100644 --- a/enterprise-api/posts/get-count-of-all-posts.mdx +++ b/enterprise-api/posts/get-count-of-all-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/counts/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-count-of-recent-posts.mdx b/enterprise-api/posts/get-count-of-recent-posts.mdx index 464df2be6..77c6b03eb 100644 --- a/enterprise-api/posts/get-count-of-recent-posts.mdx +++ b/enterprise-api/posts/get-count-of-recent-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/counts/recent ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-historical-post-insights.mdx b/enterprise-api/posts/get-historical-post-insights.mdx index 7cc69f98b..f0e90b6c0 100644 --- a/enterprise-api/posts/get-historical-post-insights.mdx +++ b/enterprise-api/posts/get-historical-post-insights.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/insights/historical ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-liking-users.mdx b/enterprise-api/posts/get-liking-users.mdx index 2c577cbcc..6a319905e 100644 --- a/enterprise-api/posts/get-liking-users.mdx +++ b/enterprise-api/posts/get-liking-users.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id}/liking_users ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-post-analytics.mdx b/enterprise-api/posts/get-post-analytics.mdx index 961c610c4..ddb2ce5e3 100644 --- a/enterprise-api/posts/get-post-analytics.mdx +++ b/enterprise-api/posts/get-post-analytics.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/analytics ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-post-by-id.mdx b/enterprise-api/posts/get-post-by-id.mdx index 00c223ada..580dbeb89 100644 --- a/enterprise-api/posts/get-post-by-id.mdx +++ b/enterprise-api/posts/get-post-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-posts-by-ids.mdx b/enterprise-api/posts/get-posts-by-ids.mdx index 87436913f..efb9a70ad 100644 --- a/enterprise-api/posts/get-posts-by-ids.mdx +++ b/enterprise-api/posts/get-posts-by-ids.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-quoted-posts.mdx b/enterprise-api/posts/get-quoted-posts.mdx index 57df7fd8a..13a425945 100644 --- a/enterprise-api/posts/get-quoted-posts.mdx +++ b/enterprise-api/posts/get-quoted-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id}/quote_tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-reposted-by.mdx b/enterprise-api/posts/get-reposted-by.mdx index a50f659af..968f17876 100644 --- a/enterprise-api/posts/get-reposted-by.mdx +++ b/enterprise-api/posts/get-reposted-by.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id}/retweeted_by ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/get-reposts.mdx b/enterprise-api/posts/get-reposts.mdx index 71026dcaa..dbd83fe84 100644 --- a/enterprise-api/posts/get-reposts.mdx +++ b/enterprise-api/posts/get-reposts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id}/retweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/hide-replies/apps.mdx b/enterprise-api/posts/hide-replies/apps.mdx index 4bc8bb760..c055606b8 100644 --- a/enterprise-api/posts/hide-replies/apps.mdx +++ b/enterprise-api/posts/hide-replies/apps.mdx @@ -1,62 +1,63 @@ ---- -title: Apps -sidebarTitle: Apps -keywords: ["hide replies apps", "reply moderation apps", "apps for hide replies", "hide replies applications", "reply moderation tools"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Apps using the hide replies endpoint - -Here's a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their technology with the X API, they created useful experiences to help all users enhance the public conversation. - - ![Clarabridge](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/hide-replies/clarabridge.jpg.twimg.1920.jpg) - -**Clarabridge** - -Clarabridge integrates hide replies so that companies can keep their X feed clean and interesting to read. Replies can be hidden manually, and agents can also use Clarabridge’s text analytics to automatically detect profanity and other language that is not in line with brand policy. - -[Go to website ▸](https://www.clarabridge.com/ "Go to website ▸") - -[Clarabridge on X](https://x.com/Clarabridge "Clarabridge on X") - - ![Perspective API template app](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/hide-replies/perspective-logo.png.twimg.1920.png) - -**Perspective API template app** - -Perspective is an artificial intelligence trained by Jigsaw (a unit within Alphabet) to detect toxic comments. This app detects a person's incoming replies, and automatically hides a reply based on the “score” that indicates how confident Perspective is that a comment is similar to toxic comments it’s seen in the past. This is an open source template app developed by X. We encourage you to personalize it to build tools for your users. - -[Use app ▸](https://quintessential-yoke.glitch.me "Use app ▸") - -[Jigsaw on X](https://x.com/jigsaw "Jigsaw on X") - - ![Reshuffle](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 150 150%22%3E%3C/svg%3E) - -**Reshuffle** - -Reshuffle is a platform to connect business applications with flexible scripts. They built an integration script to detect and hide replies that include keywords you define. To try it out, make sure you have a valid app enabled for Hide replies, then follow the instructions in the repo. - -[Go to app ▸](https://github.com/reshufflehq/reshuffle "Go to app ▸") - -[Reshuffle on X](https://x.com/reshufflehq "Reshuffle on X") - - ![Hide unwanted replies](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 396 397%22%3E%3C/svg%3E) - -**Hide unwanted replies** - -Dara Oladosu, the developer behind the popular app QuotedReplies, built an app that automatically hides replies that meet some of the criteria that he’s determined are more likely to exhibit abusive behavior, including replies that contain certain keywords he’s muted in the past. - -[Go to app ▸](https://hideunwantedreplies.com/ "Go to app ▸") - -[Dara Oladosu on X](https://x.com/dara_tobi "Dara Oladosu on X") - - ![Pandaflow](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 94 94%22%3E%3C/svg%3E) - -**Pandaflow** - -Pandaflow is a no code platform to automate workflows. They integrate the endpoint so users can programmatically hide replies based on a custom flow they define. - -[Go to app ▸](https://pandaflow.io/ "Go to app ▸") - -[Pandaflow on X](https://x.com/pandaflowio "Pandaflow on X") - +--- +title: Apps +sidebarTitle: Apps +keywords: ["hide replies apps", "reply moderation apps", "apps for hide replies", "hide replies applications", "reply moderation tools"] + +description: Here's a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their technology with the X API, they c...--- + +import { Button } from '/snippets/button.mdx'; + +## Apps using the hide replies endpoint + +Here's a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their technology with the X API, they created useful experiences to help all users enhance the public conversation. + + ![Clarabridge](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/hide-replies/clarabridge.jpg.twimg.1920.jpg) + +**Clarabridge** + +Clarabridge integrates hide replies so that companies can keep their X feed clean and interesting to read. Replies can be hidden manually, and agents can also use Clarabridge’s text analytics to automatically detect profanity and other language that is not in line with brand policy. + +[Go to website ▸](https://www.clarabridge.com/ "Go to website ▸") + +[Clarabridge on X](https://x.com/Clarabridge "Clarabridge on X") + + ![Perspective API template app](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/hide-replies/perspective-logo.png.twimg.1920.png) + +**Perspective API template app** + +Perspective is an artificial intelligence trained by Jigsaw (a unit within Alphabet) to detect toxic comments. This app detects a person's incoming replies, and automatically hides a reply based on the “score” that indicates how confident Perspective is that a comment is similar to toxic comments it’s seen in the past. This is an open source template app developed by X. We encourage you to personalize it to build tools for your users. + +[Use app ▸](https://quintessential-yoke.glitch.me "Use app ▸") + +[Jigsaw on X](https://x.com/jigsaw "Jigsaw on X") + + ![Reshuffle](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 150 150%22%3E%3C/svg%3E) + +**Reshuffle** + +Reshuffle is a platform to connect business applications with flexible scripts. They built an integration script to detect and hide replies that include keywords you define. To try it out, make sure you have a valid app enabled for Hide replies, then follow the instructions in the repo. + +[Go to app ▸](https://github.com/reshufflehq/reshuffle "Go to app ▸") + +[Reshuffle on X](https://x.com/reshufflehq "Reshuffle on X") + + ![Hide unwanted replies](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 396 397%22%3E%3C/svg%3E) + +**Hide unwanted replies** + +Dara Oladosu, the developer behind the popular app QuotedReplies, built an app that automatically hides replies that meet some of the criteria that he’s determined are more likely to exhibit abusive behavior, including replies that contain certain keywords he’s muted in the past. + +[Go to app ▸](https://hideunwantedreplies.com/ "Go to app ▸") + +[Dara Oladosu on X](https://x.com/dara_tobi "Dara Oladosu on X") + + ![Pandaflow](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 94 94%22%3E%3C/svg%3E) + +**Pandaflow** + +Pandaflow is a no code platform to automate workflows. They integrate the endpoint so users can programmatically hide replies based on a custom flow they define. + +[Go to app ▸](https://pandaflow.io/ "Go to app ▸") + +[Pandaflow on X](https://x.com/pandaflowio "Pandaflow on X") + diff --git a/enterprise-api/posts/hide-replies/integrate/manage-replies-by-topic.mdx b/enterprise-api/posts/hide-replies/integrate/manage-replies-by-topic.mdx index d9070b50e..d4e9ab224 100644 --- a/enterprise-api/posts/hide-replies/integrate/manage-replies-by-topic.mdx +++ b/enterprise-api/posts/hide-replies/integrate/manage-replies-by-topic.mdx @@ -2,7 +2,8 @@ title: Manage replies by topic sidebarTitle: Manage replies by topic keywords: ["manage replies by topic", "topic-based moderation", "reply moderation by topic", "hide replies by topic", "topic filtering"] ---- + +description: Through the hide replies endpoint, you can build integrations to help people and brands keep their conversation on topic. This page shows how to manage ...--- import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/posts/hide-replies/integrate/manage-replies-in-realtime.mdx b/enterprise-api/posts/hide-replies/integrate/manage-replies-in-realtime.mdx index 2e4b26907..119fb41cd 100644 --- a/enterprise-api/posts/hide-replies/integrate/manage-replies-in-realtime.mdx +++ b/enterprise-api/posts/hide-replies/integrate/manage-replies-in-realtime.mdx @@ -2,7 +2,8 @@ title: Manage replies by topic sidebarTitle: Manage replies by topic keywords: ["manage replies", "hide replies integration", "reply moderation", "real-time moderation", "reply management", "moderate replies"] ---- + +description: With the hide replies endpoint, you can build a workflow to helps your users hide replies that have a very high-probability of being irrelevant. Useful ...--- import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/posts/hide-replies/migrate.mdx b/enterprise-api/posts/hide-replies/migrate.mdx index 1688ed9c6..62433a19a 100644 --- a/enterprise-api/posts/hide-replies/migrate.mdx +++ b/enterprise-api/posts/hide-replies/migrate.mdx @@ -2,6 +2,8 @@ title: Migration guide sidebarTitle: Migration guide keywords: ["hide replies migration", "hide replies migrate", "migration guide", "migrate hide replies", "v2 migration"] + + --- import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/posts/hide-reply.mdx b/enterprise-api/posts/hide-reply.mdx index bcb0c86cb..f5901e5a7 100644 --- a/enterprise-api/posts/hide-reply.mdx +++ b/enterprise-api/posts/hide-reply.mdx @@ -1,3 +1,4 @@ --- openapi: put /2/tweets/{tweet_id}/hidden ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.mdx b/enterprise-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.mdx index 99b012279..755dafb55 100644 --- a/enterprise-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: Likes lookup sidebarTitle: Likes lookup keywords: ["likes lookup migration", "v1.1 to v2 likes lookup", "migrate likes lookup", "standard to v2 likes", "likes migration"] ---- + +--- ### Likes lookup: Standard v1.1 compared to X API v2 If you have been working with the standard v1.1 [GET favorites/list](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/get-favorites-list) endpoint, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 Likes lookup endpoints. @@ -33,172 +34,4 @@ Depending on your authentication library/package of choice, Bearer Token authent **Rate limits** -The standard v1.1 GET favorites/list endpoint has a 75 requests per 15 minutes per user rate limit. The corresponding liked Posts endpoint in v2 also has this same rate limit. However, this v2 endpoint also has an additional rate limit of 75 requests per 15 minutes per App. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * GET https://api.x.com/1.1/favorites/list.json - (list of Posts which are by the specified user) - * There is no v1.1 equivalent to the v2 liking users endpoint -* X API v2 endpoint: - * GET https://api.x.com/2/users/:id/liked_tweets - (list of Posts which are liked by the specified user ID) - * GET https://api.x.com/2/tweets/:id/liking_users - (list of users who liked the specified Post ID) - -**Request limitations** - -The v2 liked Posts endpoint allows you to request 5 to 100 Posts per request, but you can request all likes of a Post using pagination tokens. The v1.1 GET favorites/list endpoint also allows you to pull all likes of Posts, but you can pull from 20 to 200 Posts per request. - -For the v2 liking users endpoint, you are limited to 100 liking users per Post.  -  - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Request parameters** - -The following standard v1.1 request parameters accepted two request query parameters (user_id or screen_name). The X API v2 only accepts the numerical user ID, and it must be passed as part of the endpoint path. - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. For the standard endpoints, there are several parameters that you could use to identify which fields or sets of fields would return in the payload, while the X API v2 version simplifies these different parameters into [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions).  -  - -**New JSON format** - -X API v2 is introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return user objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values. -   - -In addition to the changes that we made to our new JSON format, we also introduced a new set of fields to the Post object including the following: - -* [conversation_id](/x-api/fundamentals/conversation-id) -* Two new [Post annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields - ---- - -## Code examples - -### Get liked Posts (v2) - - - -```bash cURL -curl "https://api.x.com/2/users/2244994945/liked_tweets?tweet.fields=created_at,public_metrics&max_results=100" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/users/2244994945/liked_tweets" - -params = { - "tweet.fields": "created_at,public_metrics", - "max_results": 100 -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user's liked Posts -for page in client.posts.get_liked_posts( - "2244994945", - tweet_fields=["created_at", "public_metrics"], - max_results=100 -): - for post in page.data: - print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get user's liked Posts -const paginator = client.posts.getLikedPosts("2244994945", { - tweetFields: ["created_at", "public_metrics"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`); - }); -} -``` - - - -### Get liking users (v2) - - - -```bash cURL -curl "https://api.x.com/2/tweets/1234567890/liking_users?user.fields=username,verified" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/1234567890/liking_users" - -params = {"user.fields": "username,verified"} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get users who liked a Post -response = client.posts.get_liking_users( - "1234567890", - user_fields=["username", "verified"] -) -for user in response.data: - print(f"{user.username} - Verified: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get users who liked a Post -const response = await client.posts.getLikingUsers("1234567890", { - userFields: ["username", "verified"], -}); - -response.data?.forEach((user) => { - console.log(`${user.username} - Verified: ${user.verified}`); -}); -``` - - +The standard v1.1 GET favorites/list endpoint has a 75 requests per 15 minutes per user rate limit. The corresponding liked Posts endpoint in v2 also has this sam \ No newline at end of file diff --git a/enterprise-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.mdx b/enterprise-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.mdx index 10fccc0dc..feb8f9756 100644 --- a/enterprise-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.mdx @@ -1,183 +1,42 @@ ---- -title: Manage Likes -sidebarTitle: Manage Likes -keywords: ["manage likes migration", "v1.1 to v2 manage likes", "migrate manage likes", "standard to v2 likes", "likes migration"] ---- - -### Manage Likes: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST favorites/create](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-create) and [POST favorites/destroy](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage Likes endpoints. - -* **Similarities** - * OAuth 1.0a User Context -* **Differences** - * Endpoint URLs and HTTP methods - * App and Project requirements - * Request parameters - -#### Similarities - -**OAuth 1.0a User Context authentication method** - -Both the endpoint versions support [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 manage favorites endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs and HTTP methods** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/favorites/create.json - (like a Post) - * POST https://api.x.com/1.1/favorites/destroy.json - (unlike a Post) -* X API v2 endpoint: - * POST https://api.x.com/2/tweets/:id/likes - (like a Post) - * DELETE https://api.x.com/2/tweets/:id/likes/:tweet_id - (unlike a Post)  - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. - - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard v1.1 | X API v2 | -| :--- | :--- | -| id | id | -| includes_entities | No equivalent | - -Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters for the POST endpoint or path parameters for the DELETE endpoint. - -Also, an id of the user liking a Post is not required when using the standard v1.1 endpoints since the [Access Tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) passed with [OAuth 1.0a User Context](/resources/fundamentals/authentication) infer which user is initiating the like/unlike. - ---- - -## Code examples - -### Like a Post (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123456789/likes" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"tweet_id": "1234567890"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/likes" -response = requests.post(url, auth=auth, json={"tweet_id": "1234567890"}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Like a Post -response = client.posts.like(user_id="123456789", tweet_id="1234567890") -print(f"Liked: {response.data.liked}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Like a Post -const response = await client.posts.like("123456789", { tweetId: "1234567890" }); -console.log(`Liked: ${response.data?.liked}`); -``` - - - -### Unlike a Post (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/users/123456789/likes/1234567890" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/likes/1234567890" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Unlike a Post -response = client.posts.unlike(user_id="123456789", tweet_id="1234567890") -print(f"Liked: {response.data.liked}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Unlike a Post -const response = await client.posts.unlike("123456789", "1234567890"); -console.log(`Liked: ${response.data?.liked}`); -``` - - +--- +title: Manage Likes +sidebarTitle: Manage Likes +keywords: ["manage likes migration", "v1.1 to v2 manage likes", "migrate manage likes", "standard to v2 likes", "likes migration"] + + +--- +### Manage Likes: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST favorites/create](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-create) and [POST favorites/destroy](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage Likes endpoints. + +* **Similarities** + * OAuth 1.0a User Context +* **Differences** + * Endpoint URLs and HTTP methods + * App and Project requirements + * Request parameters + +#### Similarities + +**OAuth 1.0a User Context authentication method** + +Both the endpoint versions support [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 manage favorites endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs and HTTP methods** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/favorites/create.json + (like a Post) + * POST https://api.x.com/1.1/favorites/destroy.json + (unlike a Post) +* X API v2 endpoint: + * POST https://api.x.com/2/tweets/:id/likes + (like a Post) + * DELETE https://api.x.com/2/tweets/:id/likes/:tweet_id + (unlike a Post)  + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated \ No newline at end of file diff --git a/enterprise-api/posts/likes/migrate/overview.mdx b/enterprise-api/posts/likes/migrate/overview.mdx index a2f869ceb..55b0fa147 100644 --- a/enterprise-api/posts/likes/migrate/overview.mdx +++ b/enterprise-api/posts/likes/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["likes migration", "likes migrate", "v1.1 to v2 likes", "likes migration guide", "migrate likes"] ---- + ## Comparing X API’s Likes endpoints diff --git a/enterprise-api/posts/lookup/integrate.mdx b/enterprise-api/posts/lookup/integrate.mdx index 7fdb77247..eca611eaf 100644 --- a/enterprise-api/posts/lookup/integrate.mdx +++ b/enterprise-api/posts/lookup/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating Post lookup keywords: ["post lookup integration", "lookup integration guide", "lookup implementation", "lookup setup", "tweet lookup integration"] --- diff --git a/enterprise-api/posts/lookup/migrate/overview.mdx b/enterprise-api/posts/lookup/migrate/overview.mdx index e86c95630..206797bff 100644 --- a/enterprise-api/posts/lookup/migrate/overview.mdx +++ b/enterprise-api/posts/lookup/migrate/overview.mdx @@ -4,6 +4,7 @@ sidebarTitle: Overview keywords: ["post lookup migration", "lookup migrate", "v1.1 to v2 lookup", "lookup migration guide", "migrate lookup"] --- + ## Comparing X API’s Posts Lookup Endpoints The v2 Posts lookup endpoints replace the standard v1.1 [GET statuses/lookup](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-lookup) and [GET statuses/show](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-show-id) endpoints. This guide is for developers migrating from these older versions to X API v2. diff --git a/enterprise-api/posts/lookup/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/posts/lookup/migrate/standard-to-twitter-api-v2.mdx index 09e171b39..9be3fcf0c 100644 --- a/enterprise-api/posts/lookup/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/lookup/migrate/standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "lookup migration", "migrate lookup", "standard to v2", "v1 to v2 lookup", "migration guide"] ---- + +--- ## Standard v1.1 compared to X API v2 If you have been working with the standard v1.1 GET statuses/show and GET statuses/lookup, this guide will help you understand the similarities and differences between the standard and X API v2 Posts lookup endpoints. @@ -31,216 +32,4 @@ App-Only authentication is likely the easiest way to get started. To learn how t #### Posts per Request Limits -The v1.1 [GET statuses/lookup](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-lookup) endpoint allows you to specify up to 100 Posts per request. This also applies to the GET /tweets endpoint. To specify a full 100 Posts, use the `ids` parameter as a query parameter with a comma-separated list of [Post IDs](/resources/fundamentals/x-ids). - -**Support for Post Edit History and Metadata** - -Both versions provide metadata that describes any edit history. Check out the Post lookup API References and the [Edit Posts fundamentals page](/x-api/fundamentals/edit-posts) for more details. - -### Differences - -#### Endpoint URLs - -- **Standard v1.1 endpoints:** - - `https://api.x.com/1.1/statuses/show` - - `https://api.x.com/1.1/statuses/lookup` - -- **X API v2 endpoint:** - - `https://api.x.com/2/tweets` - - `https://api.x.com/2/tweets/:id` - -#### App and Project Requirements - -X API v2 endpoints require credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) for authentication. X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. - -#### Response Data Format - -A significant difference between standard v1.1 and X API v2 endpoint versions is how fields are selected in the payload. - -For standard endpoints, many response fields are included by default, with options to use parameters to specify additional fields. - -X API v2, however, only delivers the Post `id` and `text` fields by default. Additional fields and objects require the use of [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. The expanded fields return in an `includes` object within the response, which can be matched to the primary Post object by matching IDs. - -For more on using fields and expansions, see the [guide on how to use fields and expansions](/x-api/fundamentals/data-dictionary). A [data format migration guide](/x-api/fundamentals/fields) also maps standard v1.1 fields to the newer v2 fields. - -Additionally, X API v2 introduces new JSON designs for objects, including the Post and [user](/x-api/fundamentals/data-dictionary#user) objects: - -- Standard endpoints return Post objects in a `statuses` array, while X API v2 uses a `data` array. -- Retweeted and Quoted Tweets in X API v2 replace "statuses" terminology. -- New terminology such as `like` replaces terms like `favorites` and `favourites`. -- Attributes with no values (e.g., `null`) are not included in X API v2 payloads. - -The Post object in X API v2 includes new fields such as: -- `conversation_id` -- Two new [annotations](/x-api/fundamentals/post-annotations) fields (`context` and `entities`) -- New [metrics](/x-api/fundamentals/metrics) fields -- `reply_setting` field showing who can reply to a given Post - -#### Request Parameters - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard | X API v2 | -|:----------|:----------| -| `id` | `ids` | - -Certain standard v1.1 parameters are **not** supported in X API v2: - -| Standard | Comment | -|:---------------------|:------------------------------------------------------------------------------------------------------------------------------| -| `tweet_mode` | Replaced by fields and expansions functionality. | -| `trim_user` | Replaced by fields and expansions. Use `author_id` expansion and `user.fields` for user data. | -| `include_my_retweet`| Provides the ID of the source Post for Retweeted Posts by the authenticating user. | -| `include_entities` | Use fields and expansions to control entities in the payload. | -| `include_ext_alt_text` | Adds `ext_alt_text` field in media entity if alt text is present. | -| `include_card_uri` | Adds `card_uri` when an ads card is attached. | -| `map` | Returns the Post ID and error message for unavailable Posts in X API v2, as opposed to nullified fields in v1.1. | - -### Code Examples - -The following examples show standard v1.1 endpoints and their v2 equivalents. Replace credentials with your actual tokens. For v2 endpoints, the token must belong to a [developer App](/resources/fundamentals/developer-apps/overview) within a [Project](/resources/fundamentals/developer-apps/overview). - -The response payloads from v1.1 will differ from v2. With v2, you can request different fields with the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. - -**Multiple Posts lookup: v1.1 `GET statuses/lookup` → v2 `GET /tweets`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/statuses/lookup.json?id=1460323737035677698%2C1460323743339741184' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/tweets?ids=1460323737035677698%2C1460323743339741184&tweet.fields=created_at&expansions=author_id&user.fields=created_at' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets" - -params = { - "ids": "1460323737035677698,1460323743339741184", - "tweet.fields": "created_at", - "expansions": "author_id", - "user.fields": "created_at" -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get multiple Posts by IDs with fields and expansions -response = client.posts.get_posts( - ids=["1460323737035677698", "1460323743339741184"], - tweet_fields=["created_at"], - expansions=["author_id"], - user_fields=["created_at"] -) - -for post in response.data: - print(f"Post: {post.text}") - print(f"Created at: {post.created_at}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get multiple Posts by IDs with fields and expansions -const response = await client.posts.getPosts({ - ids: ["1460323737035677698", "1460323743339741184"], - tweetFields: ["created_at"], - expansions: ["author_id"], - userFields: ["created_at"], -}); - -response.data?.forEach((post) => { - console.log(`Post: ${post.text}`); - console.log(`Created at: ${post.created_at}`); -}); -``` - - - -**Single Post lookup: v1.1 `GET statuses/show/:id` → v2 `GET /tweets/:id`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/statuses/show.json?id=1460323737035677698' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/tweets/1460323737035677698?tweet.fields=created_at&expansions=author_id&user.fields=created_at' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/1460323737035677698" - -params = { - "tweet.fields": "created_at", - "expansions": "author_id", - "user.fields": "created_at" -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get a single Post by ID -response = client.posts.get( - "1460323737035677698", - tweet_fields=["created_at"], - expansions=["author_id"], - user_fields=["created_at"] -) - -print(f"Post: {response.data.text}") -print(f"Created at: {response.data.created_at}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get a single Post by ID -const response = await client.posts.get("1460323737035677698", { - tweetFields: ["created_at"], - expansions: ["author_id"], - userFields: ["created_at"], -}); - -console.log(`Post: ${response.data?.text}`); -console.log(`Created at: ${response.data?.created_at}`); -``` - - \ No newline at end of file +The v1.1 [GET statuses/lookup](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-lookup) endpoint allows you to specify up to 100 Posts per request. This also applies to the GET /tweets endpoint. To specify a full 100 Posts, use the `ids` parameter as a query parameter wi \ No newline at end of file diff --git a/enterprise-api/posts/manage-tweets/integrate.mdx b/enterprise-api/posts/manage-tweets/integrate.mdx index 140f5506b..ad1a42218 100644 --- a/enterprise-api/posts/manage-tweets/integrate.mdx +++ b/enterprise-api/posts/manage-tweets/integrate.mdx @@ -4,6 +4,7 @@ sidebarTitle: Integration guide keywords: ["manage tweets integration", "tweet creation integration", "post tweet integration", "tweet management guide", "create tweet setup"] --- + import { Button } from '/snippets/button.mdx'; This page covers tools and key concepts for integrating the manage Posts endpoints into your system. diff --git a/enterprise-api/posts/manage-tweets/migrate/overview.mdx b/enterprise-api/posts/manage-tweets/migrate/overview.mdx index cf5131431..0369c21eb 100644 --- a/enterprise-api/posts/manage-tweets/migrate/overview.mdx +++ b/enterprise-api/posts/manage-tweets/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["manage tweets migration", "tweet creation migration", "v1.1 to v2", "migration guide", "migrate tweet creation"] ---- + ## Comparing X API’s manage Posts endpoints diff --git a/enterprise-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.mdx index 08359ce95..a4ee49df1 100644 --- a/enterprise-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "tweet creation migration", "migrate tweet creation", "standard to v2", "v1 to v2 tweets", "migration guide"] ---- + +--- ## Standard v1.1 compared to X API v2 If you have been working with the standard v1.1 [POST statuses/update](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-update) and [POST statuses/destroy/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-destroy-id) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 manage Posts endpoints. @@ -40,108 +41,4 @@ Both the standard v1.1 and X API v2 manage Posts ([POST statuses/update](https:/ ### App and Project requirements -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - -### Request parameters - -The following standard v1.1 request parameters accepted two request query parameters (user_id or screen_name). The X API v2 only accepts the numerical Post ID for the DELETE endpoint, and it must be passed as part of the endpoint path. - -For the POST endpoint, additional parameters will need to be passed in via the JSON body of the request. You can learn more about what parameters are available in the [API reference guide](/x-api/posts/manage-tweets/introduction). - ---- - -## Code examples - -### Create a Post (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/tweets" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"text": "Hello world!"}' -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Create a Post -response = client.posts.create(text="Hello world!") -print(f"Created Post: {response.data.id}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Create a Post -const response = await client.posts.create({ text: "Hello world!" }); -console.log(`Created Post: ${response.data?.id}`); -``` - - - -### Delete a Post (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/tweets/1234567890" \ - -H "Authorization: OAuth ..." -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Delete a Post -response = client.posts.delete("1234567890") -print(f"Deleted: {response.data.deleted}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Delete a Post -const response = await client.posts.delete("1234567890"); -console.log(`Deleted: ${response.data?.deleted}`); -``` - - +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fund \ No newline at end of file diff --git a/enterprise-api/posts/retweets/integrate.mdx b/enterprise-api/posts/retweets/integrate.mdx index ad4fc1ce8..cd00ea407 100644 --- a/enterprise-api/posts/retweets/integrate.mdx +++ b/enterprise-api/posts/retweets/integrate.mdx @@ -6,8 +6,6 @@ keywords: ["retweets integration", "retweets guide", "retweets integration guide This page covers tools and key concepts for integrating the Retweet endpoints. ---- - ## Helpful tools Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: diff --git a/enterprise-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.mdx b/enterprise-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.mdx index 6a9dcdb3b..f4fbd9ab9 100644 --- a/enterprise-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.mdx @@ -1,184 +1,185 @@ ---- -title: Manage Retweets -sidebarTitle: Manage Retweets -keywords: ["manage retweets migration", "v1.1 to v2 manage retweets", "migrate manage retweets", "standard to v2 retweets", "retweets migration"] ---- - -### Manage Retweets: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST statuses/retweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id), and [POST statuses/unretweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-unretweet-id)  endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 Retweets endpoints. - -* **Similarities** - * Authentication -* **Differences** - * Endpoint URLs and HTTP methods - * Request limitations - * App and Project requirements - * Request parameters - -#### Similarities - -**Authentication** - -Both the standard v1.1 and X API v2 manage Retweets ([POST statuses/retweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id), and [POST statuses/unretweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-unretweet-id)) endpoints use [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 Retweets lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.  - -#### Differences - -**Endpoint URLs and HTTP methods** - -* Standard v1.1 endpoints: - * https://api.x.com/1.1/statuses/retweet/:id.json - (Retweets a Post. Returns the original Post with Retweet details embedded) - * https://api.x.com/1.1/statuses/unretweet/:id.json - (Undo a Retweet. Returns the original Post with Retweet details embedded) -* X API v2 endpoint: - * https://api.x.com/2/tweets/:id/retweets - (Retweets a given Post) - * https://api.x.com/2/users/:id/retweets/:source\_tweet\_id - (Undo a Retweet of a given Post)  - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. - - -**Request parameters** - -The following standard v1.1 request parameters accepted two request query parameters (user\_id or screen\_name). The X API v2 only accepts the numerical user ID, and it must be passed as part of the endpoint path. - -| Standard v1.1 | X API v2 | -| :--- | :--- | -| **id** | **id** | -| **includes_entities** | No equivalent | - -Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters for the POST endpoint or path parameters for the DELETE endpoint. - -Also, an id of the user Retweeting a Post is not required when using the standard v1.1 endpoints since the [Access Tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) passed with [OAuth 1.0a User Context](/resources/fundamentals/authentication) infer which user is initiating the Retweet/undoing a Retweet. - ---- - -## Code examples - -### Retweet a Post (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123456789/retweets" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"tweet_id": "1234567890"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/retweets" -response = requests.post(url, auth=auth, json={"tweet_id": "1234567890"}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Retweet a Post -response = client.posts.retweet(user_id="123456789", tweet_id="1234567890") -print(f"Retweeted: {response.data.retweeted}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Retweet a Post -const response = await client.posts.retweet("123456789", { tweetId: "1234567890" }); -console.log(`Retweeted: ${response.data?.retweeted}`); -``` - - - -### Undo a Retweet (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/users/123456789/retweets/1234567890" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/retweets/1234567890" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Undo a Retweet -response = client.posts.unretweet(user_id="123456789", tweet_id="1234567890") -print(f"Retweeted: {response.data.retweeted}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Undo a Retweet -const response = await client.posts.unretweet("123456789", "1234567890"); -console.log(`Retweeted: ${response.data?.retweeted}`); -``` - - +--- +title: Manage Retweets +sidebarTitle: Manage Retweets +keywords: ["manage retweets migration", "v1.1 to v2 manage retweets", "migrate manage retweets", "standard to v2 retweets", "retweets migration"] +--- + + +### Manage Retweets: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST statuses/retweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id), and [POST statuses/unretweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-unretweet-id)  endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 Retweets endpoints. + +* **Similarities** + * Authentication +* **Differences** + * Endpoint URLs and HTTP methods + * Request limitations + * App and Project requirements + * Request parameters + +#### Similarities + +**Authentication** + +Both the standard v1.1 and X API v2 manage Retweets ([POST statuses/retweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id), and [POST statuses/unretweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-unretweet-id)) endpoints use [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 Retweets lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.  + +#### Differences + +**Endpoint URLs and HTTP methods** + +* Standard v1.1 endpoints: + * https://api.x.com/1.1/statuses/retweet/:id.json + (Retweets a Post. Returns the original Post with Retweet details embedded) + * https://api.x.com/1.1/statuses/unretweet/:id.json + (Undo a Retweet. Returns the original Post with Retweet details embedded) +* X API v2 endpoint: + * https://api.x.com/2/tweets/:id/retweets + (Retweets a given Post) + * https://api.x.com/2/users/:id/retweets/:source\_tweet\_id + (Undo a Retweet of a given Post)  + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. + + +**Request parameters** + +The following standard v1.1 request parameters accepted two request query parameters (user\_id or screen\_name). The X API v2 only accepts the numerical user ID, and it must be passed as part of the endpoint path. + +| Standard v1.1 | X API v2 | +| :--- | :--- | +| **id** | **id** | +| **includes_entities** | No equivalent | + +Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters for the POST endpoint or path parameters for the DELETE endpoint. + +Also, an id of the user Retweeting a Post is not required when using the standard v1.1 endpoints since the [Access Tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) passed with [OAuth 1.0a User Context](/resources/fundamentals/authentication) infer which user is initiating the Retweet/undoing a Retweet. + +--- + +## Code examples + +### Retweet a Post (v2) + + + +```bash cURL +curl -X POST "https://api.x.com/2/users/123456789/retweets" \ + -H "Authorization: OAuth ..." \ + -H "Content-Type: application/json" \ + -d '{"tweet_id": "1234567890"}' +``` + +```python Python +# Requires OAuth 1.0a User Context authentication +import requests +from requests_oauthlib import OAuth1 + +auth = OAuth1( + "API_KEY", "API_SECRET", + "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" +) + +url = "https://api.x.com/2/users/123456789/retweets" +response = requests.post(url, auth=auth, json={"tweet_id": "1234567890"}) +print(response.json()) +``` + +```python Python SDK +from xdk import Client +from xdk.oauth1_auth import OAuth1 + +oauth1 = OAuth1( + api_key="YOUR_API_KEY", + api_secret="YOUR_API_SECRET", + access_token="YOUR_ACCESS_TOKEN", + access_token_secret="YOUR_ACCESS_TOKEN_SECRET" +) + +client = Client(auth=oauth1) + +# Retweet a Post +response = client.posts.retweet(user_id="123456789", tweet_id="1234567890") +print(f"Retweeted: {response.data.retweeted}") +``` + +```javascript JavaScript SDK +import { Client, OAuth1 } from "@xdevplatform/xdk"; + +const oauth1 = new OAuth1({ + apiKey: "YOUR_API_KEY", + apiSecret: "YOUR_API_SECRET", + accessToken: "YOUR_ACCESS_TOKEN", + accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", +}); + +const client = new Client({ oauth1 }); + +// Retweet a Post +const response = await client.posts.retweet("123456789", { tweetId: "1234567890" }); +console.log(`Retweeted: ${response.data?.retweeted}`); +``` + + + +### Undo a Retweet (v2) + + + +```bash cURL +curl -X DELETE "https://api.x.com/2/users/123456789/retweets/1234567890" \ + -H "Authorization: OAuth ..." +``` + +```python Python +# Requires OAuth 1.0a User Context authentication +import requests +from requests_oauthlib import OAuth1 + +auth = OAuth1( + "API_KEY", "API_SECRET", + "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" +) + +url = "https://api.x.com/2/users/123456789/retweets/1234567890" +response = requests.delete(url, auth=auth) +print(response.json()) +``` + +```python Python SDK +from xdk import Client +from xdk.oauth1_auth import OAuth1 + +oauth1 = OAuth1( + api_key="YOUR_API_KEY", + api_secret="YOUR_API_SECRET", + access_token="YOUR_ACCESS_TOKEN", + access_token_secret="YOUR_ACCESS_TOKEN_SECRET" +) + +client = Client(auth=oauth1) + +# Undo a Retweet +response = client.posts.unretweet(user_id="123456789", tweet_id="1234567890") +print(f"Retweeted: {response.data.retweeted}") +``` + +```javascript JavaScript SDK +import { Client, OAuth1 } from "@xdevplatform/xdk"; + +const oauth1 = new OAuth1({ + apiKey: "YOUR_API_KEY", + apiSecret: "YOUR_API_SECRET", + accessToken: "YOUR_ACCESS_TOKEN", + accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", +}); + +const client = new Client({ oauth1 }); + +// Undo a Retweet +const response = await client.posts.unretweet("123456789", "1234567890"); +console.log(`Retweeted: ${response.data?.retweeted}`); +``` + + diff --git a/enterprise-api/posts/retweets/migrate/overview.mdx b/enterprise-api/posts/retweets/migrate/overview.mdx index 93ec33e4b..a1d51d3a0 100644 --- a/enterprise-api/posts/retweets/migrate/overview.mdx +++ b/enterprise-api/posts/retweets/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["retweets migration", "retweets migrate", "v1.1 to v2 retweets", "retweets migration guide", "migrate retweets"] ---- + ## Comparing X API’s Retweets endpoints diff --git a/enterprise-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.mdx b/enterprise-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.mdx index 9686da773..6b65d0f0e 100644 --- a/enterprise-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: Retweets lookup sidebarTitle: Retweets lookup keywords: ["retweets lookup migration", "v1.1 to v2 retweets lookup", "migrate retweets lookup", "standard to v2 retweets", "retweets migration"] ---- + +--- ### Retweets lookup: Standard v1.1 compared to X API v2 If you have been working with the standard v1.1 [v1.1 GET statuses/retweets/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets-id), [v1.1 GET statuses/retweets/:ids](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids), the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 Retweets lookup endpoints. @@ -35,103 +36,4 @@ For both v1.1 and v2 GET endpoints the max number of users that will be returned * Standard v1.1 endpoints: * https://api.x.com/1.1/statuses/retweets/:id.json - (Returns a collection of the 100 most recent Retweets of the Post specified by the `id` parameter) - * `https://api.x.com/1.1/statuses/retweeters/ids.json` - (Returns a collection of up to 100 user IDs belonging to users who have Retweeted the Post specified by the `id` parameter) -* X API v2 endpoint: - * https://api.x.com/2/tweets/:id/retweeted_by - (Returns a list of accounts who have Retweeted a given Post) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the user id , name, and username fields by default. To request any additional fields or objects, you wil need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any user fields that you request from this endpoint will return in the primary user object. Any expanded Post object and fields will return in an includes object within your response. You can then match any expanded objects back to the user object by matching the IDs located in both the user and the expanded Post object.  - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.  -   - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - -**Request parameters** - -The following standard v1.1 request parameters accepted two request query parameters (user_id or screen_name). The X API v2 only accepts the numerical user ID, and it must be passed as part of the endpoint path. - ---- - -## Code examples - -### Get users who Retweeted a Post (v2) - - - -```bash cURL -curl "https://api.x.com/2/tweets/1234567890/retweeted_by?user.fields=username,verified" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/1234567890/retweeted_by" - -params = {"user.fields": "username,verified"} -headers = {"Authorization": f"Bearer {bearer_token}"} - -response = requests.get(url, headers=headers, params=params) -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get users who Retweeted a Post -response = client.posts.get_retweeted_by( - "1234567890", - user_fields=["username", "verified"] -) -for user in response.data: - print(f"{user.username} - Verified: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get users who Retweeted a Post -const response = await client.posts.getRetweetedBy("1234567890", { - userFields: ["username", "verified"], -}); - -response.data?.forEach((user) => { - console.log(`${user.username} - Verified: ${user.verified}`); -}); -``` - - + (Returns a collection of the 100 most recent \ No newline at end of file diff --git a/enterprise-api/posts/search-all-posts.mdx b/enterprise-api/posts/search-all-posts.mdx index 5b3db39b0..7f05b4462 100644 --- a/enterprise-api/posts/search-all-posts.mdx +++ b/enterprise-api/posts/search-all-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/search-recent-posts.mdx b/enterprise-api/posts/search-recent-posts.mdx index 8559b1759..738cce63d 100644 --- a/enterprise-api/posts/search-recent-posts.mdx +++ b/enterprise-api/posts/search-recent-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/recent ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/posts/search/integrate/paginate.mdx b/enterprise-api/posts/search/integrate/paginate.mdx index 669d56870..1f280737d 100644 --- a/enterprise-api/posts/search/integrate/paginate.mdx +++ b/enterprise-api/posts/search/integrate/paginate.mdx @@ -2,7 +2,8 @@ title: Pagination sidebarTitle: Pagination keywords: ["search pagination", "pagination guide", "page through results", "pagination tokens", "search pagination", "next token"] ---- + +description: Search queries typically match on more Posts than can be returned in a single API response. When that happens, the data is returned in a series of 'pages'.--- ### Recent search pagination diff --git a/enterprise-api/posts/search/migrate/enterprise-to-twitter-api-v2.mdx b/enterprise-api/posts/search/migrate/enterprise-to-twitter-api-v2.mdx index 90fbd67cf..12b132867 100644 --- a/enterprise-api/posts/search/migrate/enterprise-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/search/migrate/enterprise-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 (Enterprise) sidebarTitle: v1 to v2 (Enterprise) keywords: ["enterprise to v2", "enterprise migration", "GNIP to v2", "enterprise search migration", "migrate enterprise", "v1 to v2 enterprise"] ---- + +--- ### Enterprise compared to X API v2 @@ -58,77 +59,4 @@ The X API v2 endpoints require that you use credentials from a Project when auth **Available time periods** -Both the enterprise API and X API v2 offer endpoints that allow you to retrieve filtered Post data for the full-archive of Posts. - -However, the X API v2 does not offer a 30 day time period endpoint like the enterprise API does. Instead it offers the aforementioned full-archive, or a 7 day time period, which align with the Native Enriched to v2 and [Activity Streams to v2](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) which can help you map enterprise fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. -  - -**Response data format** - -One of the biggest differences between the [enterprise response format](https://developer.x.com/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) and[X API v2’s format](/x-api/fundamentals/data-dictionary) is how you select which fields return in your payload. - -For the enterprise Search API, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the Post `id` and `text` fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any Post fields that you request from these endpoints will return in the primary Post object. Any expanded user, media, poll, or place objects and fields will return in an `includes` object within your response. You can then match any expanded objects back to the Post object by matching the IDs located in both the Post and the expanded object. - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a `statuses` array, while X API v2 returns a `data` array. -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as `contributors` and `user.translator_type` are being removed. -* Instead of using both `favorites` (in Post object) and `favourites` (in user object), X API v2 uses the term like. -* X is adopting the convention that JSON values with no value (for example, `null`) are not written to the payload. Post and user attributes are only included if they have non-null values. -   - -We also introduced a new set of fields to the Post object including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields -* A new `reply_setting` field, which shows you who can reply to a given Post - -And one last note. The premium response includes a `requestParameters` object at the root level, which contains the parameters that you included in your request. The v2 version instead contains a `meta` object that lives at the root level which includes the `newest_id`, `oldest_id`, `result_count`, and `next_token` if there is an additional page of results. - -**HTTP methods** - -The enterprise version of the API allows you to pass the request as either a POST HTTP method with a JSON body, or a GET HTTP method with a query string. - -V2 only allows you to use the GET HTTP method with a query string. -  - -**Request time formats** - -The enterprise version of this endpoint uses the following date/time format in both the pagination parameters and the `timePeriod` response field: `YYYYMMDDHHmm` - -The v2 endpoint uses ISO 8601/RFC 3339 date/time format in both the pagination parameters and the `start` and `end` response fields: `YYYY-MM-DDTHH:mm:ssZ - ` - -**Request parameters** - -The following is a table of the request parameters for enterprise and X API v2: - -| Enterprise | Search Posts v2 | -| :--- | :--- | -| query | query | -| maxResults | max_results | -| fromDate (YYMMDDHHmm) | start_time (YYYY-MM-DDTHH:mm:ssZ) | -| toDate (YYMMDDHHmm) | end_time (YYYY-MM-DDTHH:mm:ssZ) | -| | since_id | -| | until_id | -| next | next_token or pagination_token | - -**Filtering operators** - -While the operators between enterprise and X API v2 are mostly the same, there are some differences in operator availability and some new operators that were introduced to just the X API v2 version. - -To see a full table of the operators that are available for X API v2, enterprise, and even premium and standard, please visit the [Search Posts migration landing page](/x-api/posts/search/migrate/overview). - -**Next steps** - -[Check out our quick start guide for X API v2 full-archive search](/x-api/posts/search/quickstart/full-archive-search) - -[Review the API reference for full-archive search](/x-api/posts/full-archive-search) - -[Check out some sample code for these endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code) - +Both \ No newline at end of file diff --git a/enterprise-api/posts/search/migrate/overview.mdx b/enterprise-api/posts/search/migrate/overview.mdx index 07916c784..6990f32ed 100644 --- a/enterprise-api/posts/search/migrate/overview.mdx +++ b/enterprise-api/posts/search/migrate/overview.mdx @@ -8,8 +8,6 @@ keywords: ["search migration", "search migrate", "v1.1 to v2 search", "search mi The v2 Search Tweets endpoint will eventually replace the [standard v1.1 search/posts](/x-api/posts/search/introduction) endpoint and [enterprise Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api). If you have code, apps, or tools that use an older version of a X search endpoint and are considering migrating to the newer X API v2 endpoints, then this guide is for you. ---- - ## Recent search comparison The following table compares the various types of recent search endpoints: diff --git a/enterprise-api/posts/search/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/posts/search/migrate/standard-to-twitter-api-v2.mdx index 4dd97955f..0b35298b9 100644 --- a/enterprise-api/posts/search/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/search/migrate/standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "search migration", "migrate search", "standard to v2 search", "v1 to v2 search", "migration guide"] ---- + +--- ### Standard v1.1 compared to X API v2 If you have been working with the v1.1 [search/posts](/x-api/posts/search/introduction), the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 search Posts endpoint. @@ -35,212 +36,4 @@ If you would like to take advantage of the ability to pull private or advertisin **Support for Post edit history and metadata** -Both versions provide metadata that describes any edit history. Check out the [search API References](/x-api/posts/recent-search) and the [Post edits fundamentals page](/x-api/fundamentals/edit-posts) for more details.  - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * https://api.x.com/1.1/search/tweets - -* X API v2 endpoint: - * https://api.x.com/2/tweets/search/recent -   - - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App.  - - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any Post fields that you request from these endpoints will return in the primary Post object. Any expanded user, media, poll, or place objects and fields will return in an includes object within your response. You can then match any expanded objects back to the Post object by matching the IDs located in both the Post and the expanded object.  - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values.  -   - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - -#### Request parameters - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard search v1.1 | Search Posts v2 | -| :--- | :--- | -| q | query | -| | start_time (YYYY-MM-DDTHH:mm:ssZ) | -| until (YYYY-MM-DD) | end_time (YYYY-MM-DDTHH:mm:ssZ) | -| since_id | since_id | -| max_id | until_id | -| count | max_results | -| Response provides search\_metadata.next\_results | next_token | - -There are also a set of standard search Posts request parameters **not** supported in X API v2: - -| **Standard v1.1 parameter** | **Details** | -| :--- | :--- | -| geocode | Search Posts supports geo operators for location-based queries. | -| locale | With standard search, this was used to specify the language of the query but never fully implemented. | -| lang | Search Posts endpoints provide a lang query operator for matching on languages of interest. | -| include_entities | Post entities are always included. | -| result_type | Search Posts endpoints deliver all matching Posts, regardless of engagement level. | -| extended | X API v2 is built from the ground up to support Posts with up to 280 characters. With v2, there is no concept of 'extended' Posts. | - - -Here is an example request that shows the difference between a Standard request and a Search Posts request: - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| https://api.x.com/1.1/search/tweets.json?q=snow&count=50 | https://api.x.com/2/tweets/search/recent?query=snow&max_results=50 | - - -These requests will both return the 50 most recent Posts that contain the keyword snow. The v2 request will return the default id and text fields of the matching Posts. Here is an example of specifying additional Posts and user fields to include in the JSON payload: - -| | -| :--- | -| **X API v2** | -| https://api.x.com/2/tweets/search/recent?query=snow&max\_results=50&tweet.fields=id,created\_at,author_id,text,source,entities,attachments&user.fields=id,name,username,description | - -**New query operators** - -Search Posts introduces new operators in support of two new X API v2 features:  - -* **[Conversation IDs](/x-api/fundamentals/conversation-id)** \- As conversations unfold on X, a conservation ID will be available to mark Posts that are part of the conversation. All Posts in the conversation will have their conversation_id set to the Post ID that started it.  - * `conversation_id:` -* **[X Annotations](/x-api/fundamentals/post-annotations)** provide contextual information about Posts, and include entity and context annotations. Entities are comprised of people, places, products and organizations. Contexts are domains, or topics, that surfaced entities are a part of. For example, people mentioned in a Post may have a context that indicates whether they are an athlete, actor, or politician.   - * context: matches on Posts that have been annotated with a context of interest.  - * entity: matches on Posts that have been annotated with an entity of interest.  - -   - -#### AND / OR operator precedence  - -The basic building block for building search queries is the use of OR and AND logical groupings. The standard search API applies ORs before ANDs, while Search Posts endpoints (as well as the premium and enterprise versions) applies ANDs before ORs. This difference is critical when translating queries between the two.  - -For example, with standard search, if you wanted to match Posts with the keyword ‘storm’ that mention the word ‘colorado’ or the #COwx hashtag, you could do that with the following search query: - -storm #COwx OR colorado - -With the Search Posts operator precedence, ANDs are applied before ORs. So the above query is equivalent to:  - -(storm #COwx) OR colorado - -However, the above rule would match on any Posts that mentions ‘Colorado’, regardless if the Post mentions ‘storm’ or the #COwx hashtag. In addition it would also  match Posts that mentioned both the keyword ‘storm’ and the #COwx hashtag.  - -To make the query behave as originally intended, the OR clauses need to be grouped together. The translation of the original standard query to Search Posts would be: - -storm (#COwx OR colorado) - -These two rules have very different matching behavior. For the month of October 2019, the original rule matches over 1,175,000 Posts while the correctly translated rule matches around 5,600 Posts. Be sure to mind your ANDs and ORs, and use parentheses where needed.  - - -#### cURL requests - -**The following section displays cURL requests for the standard v1.1 endpoint and its equivalent endpoint in v2.** - -The requests are made using [OAuth 2.0 App-Only](https://developer.x.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token). In order to run the following cURL requests, you will need to replace ACCESS_TOKEN in the authorization header with your app access token. For v2 endpoints, your app access token must belong to a [developer App](/resources/fundamentals/developer-apps/overview) within a [Project](/resources/fundamentals/developer-apps/overview).  - -The response payload returned by the v1.1 endpoint will be different from the response payload returned by the v2 endpoint. With v2, the response will include the default fields, as well as any other fields requested with the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. You can use these parameters to request a different set of fields to be returned. - -**Standard v1.1 `GET search/tweets` → v2 `GET tweets/search/recent`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/search/tweets.json?q=from%3AXDevelopers%20-is%3Aretweet&count=100' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/tweets/search/recent?query=from%3AXDevelopers%20-is%3Aretweet&tweet.fields=created_at%2Cconversation_id%2Centities&max_results=100' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/search/recent" - -params = { - "query": "from:XDevelopers -is:retweet", - "tweet.fields": "created_at,conversation_id,entities", - "max_results": 100 -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -for post in response.json()["data"]: - print(f"{post['created_at']}: {post['text'][:50]}...") -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Search recent Posts - SDK handles pagination automatically -for page in client.posts.search_recent( - query="from:XDevelopers -is:retweet", - tweet_fields=["created_at", "conversation_id", "entities"], - max_results=100 -): - for post in page.data: - print(f"{post.created_at}: {post.text[:50]}...") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Search recent Posts - SDK handles pagination automatically -const paginator = client.posts.searchRecent("from:XDevelopers -is:retweet", { - tweetFields: ["created_at", "conversation_id", "entities"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`); - }); -} -``` - - - -**Next steps** - -[Check out our quick start guide for X API v2 recent search](/x-api/posts/search/quickstart/recent-search) - -[Review the API reference for recent search](/x-api/posts/recent-search) - -[Check out some sample code for these endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code "Check out some sample code for these endpoints") - -[Step-by-step guide to making your first request to recent search](/x-api/getting-started/make-your-first-request "Step-by-step guide to making your first request to recent search") - +Both versions provide metadata that describes any edit history. Check out the [search API References]( \ No newline at end of file diff --git a/enterprise-api/posts/timelines/integrate.mdx b/enterprise-api/posts/timelines/integrate.mdx index 740863c34..4030873af 100644 --- a/enterprise-api/posts/timelines/integrate.mdx +++ b/enterprise-api/posts/timelines/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating Timelines endpoints keywords: ["timeline integration", "timeline guide", "timeline implementation", "home timeline integration", "user timeline integration"] --- diff --git a/enterprise-api/posts/timelines/migrate/overview.mdx b/enterprise-api/posts/timelines/migrate/overview.mdx index a61dd05c0..e506e4baf 100644 --- a/enterprise-api/posts/timelines/migrate/overview.mdx +++ b/enterprise-api/posts/timelines/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["timeline migration", "timeline migrate", "v1.1 to v2 timeline", "timeline migration guide", "migrate timeline"] ---- + ## Comparing X API's timelines endpoints @@ -94,15 +94,4 @@ The following tables compare the standard v1.1 and X API v2 user mention timelin | Optional parameters for results refinement | count
trim_user
include_entities
tweet_mode
since_id
max_id | max_results
tweet.fields
user.fields
place.fields
media.fields
poll.fields
expansions
start_time
end_time
since_id
until_id | | Supports requesting and receiving [annotations](/x-api/fundamentals/post-annotations) | N/A | Returns Posts results with inferred anotation data based on the Post text, such as 'Music Genre' and 'Folk Music' or 'Musician' and 'Dolly Parton' | | Supports requesting and receiving specific Post [metrics](/x-api/fundamentals/metrics) | N/A | Returns Post results with available public_metrics per Post including retweet_count, reply_count, quote_count and like_count.

Available with OAuth 1.0a User Context:
Additional non\_public\_metrics , including impression_count, user\_profile\_clicks, url\_link\_clicks.

Additional media metrics such as view_count and video playback metrics.

Additional organic_metrics and promoted_metrics available with OAuth 1.0a User Context for promoted Posts | -| Supports requesting and receiving [conversation_id](/x-api/fundamentals/conversation-id) | N/A | Returns a conversation_id field where the value represents the first published Post in a reply thread to help you track conversations. | -| Post JSON format | [Standard v1.1 data format](/x-api/fundamentals/data-dictionary) | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | -| Results order | Reverse chronological | Reverse chronological | -| Request parameters for pagination | N/A must use navigation by Post ID | Results can be reviewed moving forward or backward using pagination_token | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) | | ✔ | -| Provides Post edit history | ✔ | ✔ | - -**Other migration resources** - -[Post lookup: Standard v1.1 to X API v2](/x-api/posts/lookup/migrate/standard-to-twitter-api-v2 "Post lookup: Standard v1.1 to X API v2") - -[X API migration hub](/x-api/migrate/overview) +| \ No newline at end of file diff --git a/enterprise-api/posts/timelines/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/posts/timelines/migrate/standard-to-twitter-api-v2.mdx index 9bfa2e028..88c9d3336 100644 --- a/enterprise-api/posts/timelines/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/timelines/migrate/standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "timeline migration", "migrate timeline", "standard to v2 timeline", "v1 to v2 timeline", "migration guide"] ---- + +--- import { Button } from '/snippets/button.mdx'; ## Standard v1.1 timelines to X API v2 timelines @@ -33,224 +34,4 @@ If you have been working with the v1.1 timelines endpoints (statuses/user\_timel * Different max_results (count) per response * Response data format * Request parameters - * Customized data format based on request parameters, including v2 fields and expansions - * Additional available data: metrics, Post annotations, polls - -### Similarities - -**Authentication** - -The v1.1 statuses/user_timeline and the X API v2 user Post timeline endpoint support both [OAuth 1.0a User Context](/resources/fundamentals/authentication) and [OAuth 2.0 App-Only](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). Therefore, you can continue using the same authentication method and authorization tokens if you migrate to the X API v2 version. - -**Historical Access** - -The v1.1 statuses/user_timeline and the X API v2 user Post timeline endpoint both will return the most recent 3200 Posts, including Retweets - -The v1.1 statuses/mentions_timeline and the X API v2 user mention timeline endpoint can return the most recent 800 Posts. - -**Support for Post edit history and metadata** - -Both versions provide metadata that describes any edit history. Check out the [filtered stream API References](/x-api/posts/filtered-stream/introduction) and the [Edit Posts fundamentals page](/x-api/fundamentals/edit-posts) for more details. - -**Rate Limits** - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| user_timeline:

900 requests per 15 min with OAuth 1.0a User Context

1500 requests per 15 min with OAuth 2.0 App-Only | User Posts timeline:

900 requests per 15-minute window with OAuth 1.0a User Context

1500 requests per 15-minute window with OAuth 2.0 App-Only | - -**Refresh polling using since_id** - -Both versions allow polling for recent results using the since_id. - -**Traversing timelines by Post IDs** - -Both endpoints have the capability to traverse through timelines using Post ID 'timestamps' based on the way Post IDs are constructed. The functionality is generally the same except for the following: - -| | | -| :--- | :--- | -| **Standard timelines v1.1** | **timelines v2** | -| since_id (exclusive)

max_id (inclusive) | since_id (exclusive)

until_id (also exclusive, vs max_id which was inclusive) | - -**Response filtering parameters** - -| | | -| :--- | :--- | -| **Standard timelines v1.1** | **timelines v2** | -| Response filtering parameters:

* include_rts
* exclude_replies | Response filtering parameters:

* exclude=retweets,replies | -| Example

https://api.x.com/1.1/statuses/user\_timeline.json?user\_id=2244994945&include\_rts=0&&exclude\_replies=1 | Example:

https://api.x.com/2/users/2244994945/tweets?max_results=100&exclude=retweets,replies | -| Notes:

For user_timeline:

* Using include_rts=0 does not change the possible historical Post limit of the most recent 3200 | Notes:

For user Posts timeline:

* Using exclude=retweets does not change the possible historical Post limit of the most recent 3200
* Using exclude=replies reduces the possible historical Post limit to the most recent 800 replies | - -### Differences - -**Authentication** - -**The v1.1 statuses/mentions_timeline endpoint only supports [OAuth 1.0a User Context](https://developer-staging.x.com/resources/fundamentals/authentication). The X API v2 user mention timeline endpoint supports both [OAuth 1.0a User Context](/resources/fundamentals/authentication),[OAuth 2.0 App-Only](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only), and [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authenticationoauth-2-0/authorization-code "This method allows an authorized app to act on behalf of the user, as the user. It is typically used to access or post public information for a specific user, and it us useful when your app needs to be aware of the relationship between a user and what this endpoint returns. Click to learn how to authenticate with OAuth 2.0 Authorization Code with PKCE.") ** - -If you would like to take advantage of the ability to access private or promoted metrics using the X API v2 user Post timeline endpoint, you will need to use OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, and pass the user access tokens related to the user who posted the Post for which you would like to access metrics. - - -**Endpoint URLs** - -Note that the X API v2 timelines endpoints require a path parameter of :id for the user ID. - -* Standard v1.1 endpoints: - * https://api.x.com/1.1/statuses/home_timeline - * https://api.x.com/1.1/statuses/user_timeline - * https://api.x.com/1.1/statuses/mention_timeline -* X API v2 endpoint: - * https://api.x.com/2/users/:id/timelines/reverse_chronological - * https://api.x.com/2/users/:id/tweets - * https://api.x.com/2/users/:id/mentions - - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Rate Limits** - -| | | -| :--- | :--- | -| **mentions_timeline:**

75 requests per 15 min with OAuth 1.0a User Context | **user mention timeline: **

180 requests per 15-minute window with OAuth 1.0a User Context
450 requests per 15-minute window with OAuth 2.0 Bearer Token | -| **home_timelime:**

15 requests per 15 minutes

Up to 800 Posts are obtainable on the home timeline | **reverse chronological home timeline:**

180 requests per 15 minutes

You can return every Post created on a timeline over the last 7 days as well as the most recent 800 regardless of creation date. | - -**Request parameters** - -| | | -| :--- | :--- | -| **Standard timelines v1.1** | **timelines v2** | -| Required: user_id or screen_name | Required: The specific user ID is specified in the path parameter | -| Optional:

count \- sets the maximum results returned per request

exclude_replies \- removes replies from the results

Include_rts \- when set to 0 removes retweets from the results

trim_user \- removes rehydrated user objects from the results

tweet_mode \- sets the data format returned for the results, set to extended for Posts longer than 140

since_id \- sets the earliest Post ID in result (exclusive)

max_id \- sets the latest Post ID in result (inclusive) | Optional:

max_results \- sets the maximum results returned per request

exclude=retweets,replies \- removes Retweets or replies from the results

tweet.fields \- sets the Post object fields to return

user.fields \- sets the User object fields to return

place.fields \- sets the place object fields to return

media.fields \- sets the media object fields to return

poll.fields \- sets the poll object fields to return

expansions - sets the expanded fields and data to return

start_time \- sets the earliest created_at time for the results

end_time \- sets the latest created_at time for the results

since_id \- sets the earliest Post ID for the results (exclusive)

until_id \- sets the latest Post ID in result (exclusive) | - -**Response data format** - -| | | -| :--- | :--- | -| **Standard search v1.1** | **Search Posts v2** | -| \[
tweet object,
tweet object
\] |
"data": \[id,text,id,text\],
"meta":
"oldest_id": "1337085692623646724",
"newest_id": "1334183616172019713",
"previous_token": "77qpymm88g5h9vqkluldpw91lr0qzfz1sqydh841iz48k",
"result_count": 10,
"next_token": "7140dibdnow9c7btw3w29gqolns6a1ipl3kzeae41vsxk"

| - -**X API v2 JSON format** - -X API v2 is introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. You can learn more about the X API v2 format, how to use fields and expansions by visiting our [guide](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions), and by reading through our broader [data dictionary](/x-api/fundamentals/data-dictionary) - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array. -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. -* Instead of using both favorites (in Post object) and favorites (in user object), X API v2 uses the term like. -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null value. - - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. For the standard endpoints, there are several parameters that you could use to identify which fields or sets of fields would return in the payload, while the X API v2 version simplifies these different parameters into [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions). - -* fields: X API v2 endpoints enable you to select which fields are provided in your payload. For example, Post, user, Media, Place, and Poll objects all have a list of fields that can be returned (or not). -* expansions: Used to expand the complementary objects referenced in Post JSON payloads. For example, all Retweets and Replies reference other Posts. By setting expansions=referenced_tweets.id, these other Post objects are expanded according to the tweet.fields setting. Other objects such as users, polls, and media can be expanded. - -* conversation_id -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields - - -We have put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. - ---- - -## Code examples - -### User Posts timeline (v2) - - - -```bash cURL -curl "https://api.x.com/2/users/2244994945/tweets?max_results=100&tweet.fields=created_at,public_metrics&exclude=retweets,replies" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user's Posts timeline -for page in client.posts.get_user_posts( - "2244994945", - tweet_fields=["created_at", "public_metrics"], - exclude=["retweets", "replies"], - max_results=100 -): - for post in page.data: - print(f"{post.created_at}: {post.text[:50]}...") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get user's Posts timeline -const paginator = client.posts.getUserPosts("2244994945", { - tweetFields: ["created_at", "public_metrics"], - exclude: ["retweets", "replies"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`); - }); -} -``` - - - -### User mentions timeline (v2) - - - -```bash cURL -curl "https://api.x.com/2/users/2244994945/mentions?max_results=100&tweet.fields=created_at,author_id" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user's mentions -for page in client.posts.get_user_mentions( - "2244994945", - tweet_fields=["created_at", "author_id"], - max_results=100 -): - for post in page.data: - print(f"Mentioned by {post.author_id}: {post.text[:50]}...") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get user's mentions -const paginator = client.posts.getUserMentions("2244994945", { - tweetFields: ["created_at", "author_id"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`Mentioned by ${post.author_id}: ${post.text?.slice(0, 50)}...`); - }); -} -``` - - - -**Next steps** - -[Check out our quick start guide for X API v2 Post lookup](/x-api/posts/lookup/quickstart "Check out our quick start guide for X API v2 Post lookup") - -[Review the API references for v2 Post lookup](/x-api/posts/lookup/migrate/overview "Review the API references for v2 Post lookup") - -[Check out our sample code for the timelines endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code "Check out our sample code for the timelines endpoints") + * Custom \ No newline at end of file diff --git a/enterprise-api/powerstream/handling-disconnections.mdx b/enterprise-api/powerstream/handling-disconnections.mdx index 9eb6499e5..55e96d92b 100644 --- a/enterprise-api/powerstream/handling-disconnections.mdx +++ b/enterprise-api/powerstream/handling-disconnections.mdx @@ -2,6 +2,8 @@ title: Handling disconnections sidebarTitle: Handling disconnections keywords: ["powerstream disconnections", "handle disconnections", "reconnect powerstream", "stream disconnections", "powerstream errors"] + + --- This page covers Powerstream-specific disconnection handling. For comprehensive guidance on handling disconnections across all streaming endpoints, see the [Handling disconnections fundamentals guide](/x-api/fundamentals/handling-disconnections). diff --git a/enterprise-api/powerstream/introduction.mdx b/enterprise-api/powerstream/introduction.mdx index 39cbee112..bf602a358 100644 --- a/enterprise-api/powerstream/introduction.mdx +++ b/enterprise-api/powerstream/introduction.mdx @@ -2,8 +2,9 @@ title: Introduction sidebarTitle: Introduction keywords: ["powerstream", "powerstream API", "real-time streaming", "low latency streaming", "streaming rules", "filtered stream", "enterprise streaming", "GNIP powerstream"] ---- + +--- Powerstream is our **lowest-latency streaming API** for accessing public X data in real-time. Unlike other streaming endpoints that prioritize data hydration and delivery (with ~6-7 seconds P99 latency), Powerstream is optimized for speed and delivers data with minimal delay. Similar to the legacy GNIP Powertrack API, it uses rules to filter Posts based on keywords, operators, and metadata. Once a persistent HTTP connection is made to the Powerstream endpoint, you can start receiving matching Posts in real-time. @@ -27,281 +28,4 @@ We'll be happy to discuss how Powerstream can support your needs. This section showcases how to quickly get started with the PowerStream endpoints using Python with the `requests` library. Install it via `pip install requests`. All examples use OAuth 2.0 Bearer Token authentication. Replace `YOUR_BEARER_TOKEN` with your actual token (store it securely, e.g., via `os.getenv('BEARER_TOKEN')`). -We'll cover each endpoint with code snippets. Assume these imports at the top: - -```python -import requests -import json -import time -import sys -import os # For env vars -``` - -### Setup -```python -bearer_token = os.getenv('BEARER_TOKEN') or "YOUR_BEARER_TOKEN" # Use env var for security -base_url = "https://api.x.com/2/powerstream" -rules_url = f"{base_url}/rules" # For rule management -headers = { - "Authorization": f"Bearer {bearer_token}", - "Content-Type": "application/json" -} -``` - -### 1. Create Rules (POST /rules) -Add rules to filter your stream. - -```python -data = { - "rules": [ - { - "value": "(cat OR dog) lang:en -is:retweet", - "tag": "pet-monitor" - }, - # Add more rules as needed (up to 100) - ] -} - -response = requests.post(rules_url, headers=headers, json=data) -if response.status_code == 201: - rules_added = response.json().get("data", {}).get("rules", []) - print("Rules added:") - for rule in rules_added: - print(f"ID: {rule['id']}, Value: {rule['value']}, Tag: {rule.get('tag', 'N/A')}") -else: - print(f"Error {response.status_code}: {response.text}") -``` - -### 2. Delete Rules (POST /rules) -Remove rules by ID (recommended) or value. - -```python -data = { - "rules": [ - { - "value": "(cat OR dog) lang:en -is:retweet", - "tag": "pet-monitor" - }, - # Add more rules as needed (up to 100) - ] -} - -response = requests.delete(rules_url, headers=headers, json=data) -if response.status_code == 200: - deleted = response.json().get("data", {}) - print(f"Deleted count: {deleted.get('deleted', 'N/A')}") - if 'not_deleted' in deleted: - print("Not deleted:", deleted['not_deleted']) -else: - print(f"Error {response.status_code}: {response.text}") -``` - -**Tip**: To delete all rules, first GET them, extract IDs, then delete in bulk. - -### 3. Get Rules (GET /rules) -Fetch all active rules. - -```python -response = requests.get(rules_url, headers=headers) -if response.status_code == 200: - rules = response.json().get("data", {}).get("rules", []) - if rules: - print("Active rules:") - for rule in rules: - print(f"ID: {rule['id']}, Value: {rule['value']}, Tag: {rule.get('tag', 'N/A')}") - else: - print("No active rules.") -else: - print(f"Error {response.status_code}: {response.text}") -``` - -### 4. PowerStream (GET /stream) -Connect to the stream for real-time, low-latency Posts. Use `stream=True` for line-by-line reading. Implement reconnect logic for robustness. - -```python -stream_url = base_url - -def main(): - while True: - response = requests.request("GET", stream_url, headers=headers, stream=True) - print(response.status_code) - for response_line in response.iter_lines(): - if response_line: - json_response = json.loads(response_line) - print(json.dumps(json_response, indent=4, sort_keys=True)) - if response.status_code != 200: - print(response.headers) - raise Exception( - "Request returned an error: {} {}".format( - response.status_code, response.text - ) - ) -``` - -#### Local Datacenter Support - -For latency optimization, Powerstream provides an option to fetch only posts that originated or were created in the local datacenter where a connection is established. This avoids replication lag, resulting in faster delivery compared to posts from other datacenters. To enable this, append the query parameter `?localDcOnly=true` to the stream endpoint (e.g., `/2/powerstream?localDcOnly=true`). The datacenter you are connected to will be indicated both in the initial data payload of the stream and as an HTTP header in the response. - -To use in code: - -```python -# For local datacenter only: -stream_url = "https://api.x.com/2/powerstream?localDcOnly=true" -``` - -If the `localDcOnly` parameter is enabled, when the stream first connects, it will include the following response headers indicating which local datacenter is being used: - -```bash -'x-powerstream-datacenter': 'atla', -'x-powerstream-localdconly': 'true' -``` - -In addition to this, it will also send an initial payload specifying the datacenter: - -```bash -{ - "type": "connection_metadata", - "datacenter": "atla", - "timestamp": 1762557264155 -} -``` - - -**Tip:** To optimize latency, set up connections from different geographic locations (e.g., one near Atlanta on the US East Coast and another near Portland on the US West Coast), enabling `localDcOnly=true` for each. This provides faster access to posts from each respective datacenter. Aggregate the streams on your end to combine cross-datacenter data. - - -## Operators - -In order to set rules for filtering, you can use keywords and operators. - - - Complete list of available operators - - ---- - -## Responses - -The payload of the Powestream API is the same format as the legacy GNIP Powertrack API. A sample json response looks like: - -```json -[ - { - "created_at": "Tue Mar 21 20:50:14 +0000 2006", - "id": 20, - "id_str": "20", - "text": "just setting up my twttr", - "truncated": false, - "entities": { - "hashtags": [], - "symbols": [], - "user_mentions": [], - "urls": [] - }, - "source": "X Web Client", - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 12, - "id_str": "12", - "name": "jack", - "screen_name": "jack", - "location": "", - "description": "no state is the best state", - "url": "https://t.co/ZEpOg6rn5L", - "entities": { - "url": { - "urls": [ - { - "url": "https://t.co/ZEpOg6rn5L", - "expanded_url": "http://primal.net/jack", - "display_url": "primal.net/jack", - "indices": [ - 0, - 23 - ] - } - ] - }, - "description": { - "urls": [] - } - }, - "protected": false, - "followers_count": 6427829, - "friends_count": 3, - "listed_count": 32968, - "created_at": "Tue Mar 21 20:50:14 +0000 2006", - "favourites_count": 36306, - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "verified": false, - "statuses_count": 30134, - "lang": null, - "contributors_enabled": false, - "is_translator": false, - "is_translation_enabled": false, - "profile_background_color": "EBEBEB", - "profile_background_image_url": "http://abs.twimg.com/images/themes/theme7/bg.gif", - "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme7/bg.gif", - "profile_background_tile": false, - "profile_image_url": "http://pbs.twimg.com/profile_images/1661201415899951105/azNjKOSH_normal.jpg", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/1661201415899951105/azNjKOSH_normal.jpg", - "profile_banner_url": "https://pbs.twimg.com/profile_banners/12/1742427520", - "profile_link_color": "990000", - "profile_sidebar_border_color": "DFDFDF", - "profile_sidebar_fill_color": "F3F3F3", - "profile_text_color": "333333", - "profile_use_background_image": true, - "has_extended_profile": true, - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null, - "translator_type": "regular", - "withheld_in_countries": [] - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "retweet_count": 122086, - "favorite_count": 263321, - "favorited": false, - "retweeted": false, - "lang": "en" - } -] -``` - -## Limits & Best Practices - -- Rate Limits: 50 requests/24h for rule management; no limit on streams (but connection limits apply). -- Reconnection: Exponential backoff on disconnects. -- Monitoring: Use `Connection: keep-alive` headers. - ---- - -## Streaming fundamentals - - - - Best practices for streaming clients - - - Reconnect gracefully - - - Handle high throughput - - - Build resilient applications - - - +We'll cover each en \ No newline at end of file diff --git a/enterprise-api/spaces/get-space-by-id.mdx b/enterprise-api/spaces/get-space-by-id.mdx index 6c70950fe..4374a22c1 100644 --- a/enterprise-api/spaces/get-space-by-id.mdx +++ b/enterprise-api/spaces/get-space-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/spaces/get-space-posts.mdx b/enterprise-api/spaces/get-space-posts.mdx index 7efff44e6..e1fbd9acb 100644 --- a/enterprise-api/spaces/get-space-posts.mdx +++ b/enterprise-api/spaces/get-space-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/{id}/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/spaces/get-space-ticket-buyers.mdx b/enterprise-api/spaces/get-space-ticket-buyers.mdx index 56e225303..fc500b9a7 100644 --- a/enterprise-api/spaces/get-space-ticket-buyers.mdx +++ b/enterprise-api/spaces/get-space-ticket-buyers.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/{id}/buyers ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/spaces/get-spaces-by-creator-ids.mdx b/enterprise-api/spaces/get-spaces-by-creator-ids.mdx index dce7f72fe..10ce0c8e0 100644 --- a/enterprise-api/spaces/get-spaces-by-creator-ids.mdx +++ b/enterprise-api/spaces/get-spaces-by-creator-ids.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/by/creator_ids ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/spaces/get-spaces-by-ids.mdx b/enterprise-api/spaces/get-spaces-by-ids.mdx index 309f3571a..89a151c81 100644 --- a/enterprise-api/spaces/get-spaces-by-ids.mdx +++ b/enterprise-api/spaces/get-spaces-by-ids.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/spaces/introduction.mdx b/enterprise-api/spaces/introduction.mdx index 9b1dde449..9c605f935 100644 --- a/enterprise-api/spaces/introduction.mdx +++ b/enterprise-api/spaces/introduction.mdx @@ -2,7 +2,8 @@ title: Introduction sidebarTitle: Introduction keywords: ["spaces", "X spaces", "audio spaces", "live audio", "spaces API", "spaces lookup", "spaces search", "spaces discovery"] ---- + +description: The following page describes the Spaces endpoints included in the X API. To learn more about Spaces in general, please visit [help.--- import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/spaces/search-spaces.mdx b/enterprise-api/spaces/search-spaces.mdx index eb3ee21ea..a1289a7ed 100644 --- a/enterprise-api/spaces/search-spaces.mdx +++ b/enterprise-api/spaces/search-spaces.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/search ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/get-stream-rule-counts.mdx b/enterprise-api/stream/get-stream-rule-counts.mdx index e4708bd99..f2e7dacf1 100644 --- a/enterprise-api/stream/get-stream-rule-counts.mdx +++ b/enterprise-api/stream/get-stream-rule-counts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/stream/rules/counts ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/get-stream-rules.mdx b/enterprise-api/stream/get-stream-rules.mdx index 33f6bcc4f..3d22916c2 100644 --- a/enterprise-api/stream/get-stream-rules.mdx +++ b/enterprise-api/stream/get-stream-rules.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/stream/rules ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-10-sampled-posts.mdx b/enterprise-api/stream/stream-10-sampled-posts.mdx index eb757f977..8caaf83ed 100644 --- a/enterprise-api/stream/stream-10-sampled-posts.mdx +++ b/enterprise-api/stream/stream-10-sampled-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/sample10/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-all-likes.mdx b/enterprise-api/stream/stream-all-likes.mdx index 396ea3b1a..dcc95b92a 100644 --- a/enterprise-api/stream/stream-all-likes.mdx +++ b/enterprise-api/stream/stream-all-likes.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/likes/firehose/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-all-posts.mdx b/enterprise-api/stream/stream-all-posts.mdx index 0176b635a..552fb99cf 100644 --- a/enterprise-api/stream/stream-all-posts.mdx +++ b/enterprise-api/stream/stream-all-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-english-posts.mdx b/enterprise-api/stream/stream-english-posts.mdx index 05f99f6a2..e6a8b1bc9 100644 --- a/enterprise-api/stream/stream-english-posts.mdx +++ b/enterprise-api/stream/stream-english-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream/lang/en ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-filtered-posts.mdx b/enterprise-api/stream/stream-filtered-posts.mdx index 67ae7d5fc..afa18701b 100644 --- a/enterprise-api/stream/stream-filtered-posts.mdx +++ b/enterprise-api/stream/stream-filtered-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-japanese-posts.mdx b/enterprise-api/stream/stream-japanese-posts.mdx index 26113910b..f6e8fe9fc 100644 --- a/enterprise-api/stream/stream-japanese-posts.mdx +++ b/enterprise-api/stream/stream-japanese-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream/lang/ja ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-korean-posts.mdx b/enterprise-api/stream/stream-korean-posts.mdx index 53b779919..32d4b1d37 100644 --- a/enterprise-api/stream/stream-korean-posts.mdx +++ b/enterprise-api/stream/stream-korean-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream/lang/ko ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-likes-compliance-data.mdx b/enterprise-api/stream/stream-likes-compliance-data.mdx index ab366b9b1..852e9d14e 100644 --- a/enterprise-api/stream/stream-likes-compliance-data.mdx +++ b/enterprise-api/stream/stream-likes-compliance-data.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/likes/compliance/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-portuguese-posts.mdx b/enterprise-api/stream/stream-portuguese-posts.mdx index f1da8cd4d..85e1e04c8 100644 --- a/enterprise-api/stream/stream-portuguese-posts.mdx +++ b/enterprise-api/stream/stream-portuguese-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream/lang/pt ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-post-labels.mdx b/enterprise-api/stream/stream-post-labels.mdx index 48a78208d..e14e2566d 100644 --- a/enterprise-api/stream/stream-post-labels.mdx +++ b/enterprise-api/stream/stream-post-labels.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/label/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-posts-compliance-data.mdx b/enterprise-api/stream/stream-posts-compliance-data.mdx index dc834d156..78a55261c 100644 --- a/enterprise-api/stream/stream-posts-compliance-data.mdx +++ b/enterprise-api/stream/stream-posts-compliance-data.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/compliance/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-sampled-likes.mdx b/enterprise-api/stream/stream-sampled-likes.mdx index f073bb2b5..fd045533b 100644 --- a/enterprise-api/stream/stream-sampled-likes.mdx +++ b/enterprise-api/stream/stream-sampled-likes.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/likes/sample10/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-sampled-posts.mdx b/enterprise-api/stream/stream-sampled-posts.mdx index 140cea99c..1bace5451 100644 --- a/enterprise-api/stream/stream-sampled-posts.mdx +++ b/enterprise-api/stream/stream-sampled-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/sample/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/stream-users-compliance-data.mdx b/enterprise-api/stream/stream-users-compliance-data.mdx index a78937542..89f03329a 100644 --- a/enterprise-api/stream/stream-users-compliance-data.mdx +++ b/enterprise-api/stream/stream-users-compliance-data.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/compliance/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/stream/update-stream-rules.mdx b/enterprise-api/stream/update-stream-rules.mdx index e69e135c1..daf478ebc 100644 --- a/enterprise-api/stream/update-stream-rules.mdx +++ b/enterprise-api/stream/update-stream-rules.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/tweets/search/stream/rules ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/trends/get-ai-trends-by-id.mdx b/enterprise-api/trends/get-ai-trends-by-id.mdx index aa8d55508..9c8de6c2d 100644 --- a/enterprise-api/trends/get-ai-trends-by-id.mdx +++ b/enterprise-api/trends/get-ai-trends-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/ai_trends/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/trends/get-personalized-trends.mdx b/enterprise-api/trends/get-personalized-trends.mdx index b2b7aecf0..fdb61263b 100644 --- a/enterprise-api/trends/get-personalized-trends.mdx +++ b/enterprise-api/trends/get-personalized-trends.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/personalized_trends ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/trends/get-trends-by-woeid.mdx b/enterprise-api/trends/get-trends-by-woeid.mdx index c591cdff5..349a005a6 100644 --- a/enterprise-api/trends/get-trends-by-woeid.mdx +++ b/enterprise-api/trends/get-trends-by-woeid.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/trends/by/woeid/{woeid} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/usage/get-usage.mdx b/enterprise-api/usage/get-usage.mdx index fe624116f..ac3cc6c3c 100644 --- a/enterprise-api/usage/get-usage.mdx +++ b/enterprise-api/usage/get-usage.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/usage/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/block-dms.mdx b/enterprise-api/users/block-dms.mdx index 6b9e9b883..7212e4e36 100644 --- a/enterprise-api/users/block-dms.mdx +++ b/enterprise-api/users/block-dms.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/dm/block ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/blocks/integrate.mdx b/enterprise-api/users/blocks/integrate.mdx index 1c534e606..a670874f5 100644 --- a/enterprise-api/users/blocks/integrate.mdx +++ b/enterprise-api/users/blocks/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating blocks endpoints keywords: ["blocks integration", "block users integration", "blocks guide"] --- diff --git a/enterprise-api/users/blocks/migrate.mdx b/enterprise-api/users/blocks/migrate.mdx index 334f8b1f4..581cb8ddf 100644 --- a/enterprise-api/users/blocks/migrate.mdx +++ b/enterprise-api/users/blocks/migrate.mdx @@ -2,8 +2,9 @@ title: Migration guide sidebarTitle: Migration guide keywords: ["blocks migration", "blocks migrate", "v1.1 to v2 blocks", "blocks migration guide", "migrate blocks"] ---- + +--- import { Button } from '/snippets/button.mdx'; @@ -41,194 +42,4 @@ Both the standard v1.1 and X API v2 blocks lookup endpoints use [OAuth 1.0a User * X API v2 endpoint: * GET https://api.x.com/2/users/:id/blocking (list of users who are blocked by the specified user ID) -   - -**Users per request limits** - -The standard v1.1 endpoints allow you to return up to 5000 users per request. The new v2 endpoints allow you to return up to 1000 users per request. To return a full 1000 users, you will need to pass max_results=1000 as a query parameter; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request. -  - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the user id , name, and username fields by default. To request any additional fields or objects, you wil need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any user fields that you request from this endpoint will return in the primary user object. Any expanded Post object and fields will return in an includes object within your response. You can then match any expanded objects back to the user object by matching the IDs located in both the user and the expanded Post object.  - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [P](/x-api/fundamentals/data-dictionary#tweet)ost and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.  -   - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - -**Request parameters** - -The following standard v1.1 request parameters accepted two request query parameters (user_id or screen_name). The X API v2 only accepts the numerical user ID, and it must be passed as part of the endpoint path. - ---- - -## Code examples - -### Get blocked users (v2) - - - -```bash cURL -curl "https://api.x.com/2/users/123456789/blocking?user.fields=username,verified&max_results=100" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/blocking" -params = {"user.fields": "username,verified", "max_results": 100} - -response = requests.get(url, auth=auth, params=params) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Get blocked users with pagination -for page in client.users.get_blocking( - "123456789", - user_fields=["username", "verified"], - max_results=100 -): - for user in page.data: - print(f"{user.username} - Verified: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Get blocked users with pagination -const paginator = client.users.getBlocking("123456789", { - userFields: ["username", "verified"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((user) => { - console.log(`${user.username} - Verified: ${user.verified}`); - }); -} -``` - - - -### Block a user (v2) — Enterprise only - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123456789/blocking" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"target_user_id": "2244994945"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/blocking" -response = requests.post(url, auth=auth, json={"target_user_id": "2244994945"}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Block a user -response = client.users.block( - source_user_id="123456789", - target_user_id="2244994945" -) -print(f"Blocking: {response.data.blocking}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Block a user -const response = await client.users.block("123456789", { - targetUserId: "2244994945", -}); -console.log(`Blocking: ${response.data?.blocking}`); -``` - - +   \ No newline at end of file diff --git a/enterprise-api/users/create-bookmark.mdx b/enterprise-api/users/create-bookmark.mdx index 7474d20cd..62cbefe9a 100644 --- a/enterprise-api/users/create-bookmark.mdx +++ b/enterprise-api/users/create-bookmark.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/bookmarks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/delete-bookmark.mdx b/enterprise-api/users/delete-bookmark.mdx index 78d0e4078..22457d0af 100644 --- a/enterprise-api/users/delete-bookmark.mdx +++ b/enterprise-api/users/delete-bookmark.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/bookmarks/{tweet_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/follow-list.mdx b/enterprise-api/users/follow-list.mdx index e1220a1f9..2ddb6775e 100644 --- a/enterprise-api/users/follow-list.mdx +++ b/enterprise-api/users/follow-list.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/followed_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/follow-user.mdx b/enterprise-api/users/follow-user.mdx index 449d74830..6bd98c729 100644 --- a/enterprise-api/users/follow-user.mdx +++ b/enterprise-api/users/follow-user.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/following ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/follows/migrate/overview.mdx b/enterprise-api/users/follows/migrate/overview.mdx index c8fcb118a..30cdb607a 100644 --- a/enterprise-api/users/follows/migrate/overview.mdx +++ b/enterprise-api/users/follows/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["follows migration", "follows migrate", "v1.1 to v2 follows", "follows migration guide", "migrate follows"] ---- + import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/users/follows/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/users/follows/migrate/standard-to-twitter-api-v2.mdx index e0bb58be5..a599856ef 100644 --- a/enterprise-api/users/follows/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/users/follows/migrate/standard-to-twitter-api-v2.mdx @@ -1,197 +1,47 @@ ---- -title: v1 to v2 -sidebarTitle: v1 to v2 -keywords: ["v1.1 to v2 migration", "follows migration", "migrate follows", "standard to v2 follows", "v1 to v2 follows", "migration guide"] ---- - -import { Button } from '/snippets/button.mdx'; - -#### Manage follows: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST friendships/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create) and [POST friendships/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 manage follows endpoints. - -* **Similarities** - * OAuth 1.0a User Context -* **Differences** - * Endpoint URLs - * App and Project requirements - * HTTP methods - * Request parameters - - - -#### Similarities - -**OAuth 1.0a User Context authentication method** - -Both the endpoint versions support [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 manage follows endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/friendships/create.json - (follow a user) - * POST https://api.x.com/1.1/friendships/destroy.json - (unfollow a user) -* X API v2 endpoint: - * POST https://api.x.com/2/users/:id/following - (follow a user) - * DELETE https://api.x.com/2/users/:source\_user\_id/following/:target\_user\_id - (unfollow a user) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard v1.1 | X API v2 | -| :--- | :--- | -| No equivalent | id (POST), source\_user\_id (DELETE) | -| user_id | target\_user\_id | -| screen_name | No equivalent | - -Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters (for the POST endpoint) or path parameters (for the DELETE endpoint). - -Also, the v2 id and source\_user\_id are not required when using the standard v1.1 endpoints since the Access Tokens passed with OAuth 1.0a User Context inferred which user was initiating the follow/unfollow. - ---- - -## Code examples - -### Follow a user (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123456789/following" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"target_user_id": "2244994945"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/following" -response = requests.post(url, auth=auth, json={"target_user_id": "2244994945"}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Follow a user -response = client.users.follow( - source_user_id="123456789", - target_user_id="2244994945" -) -print(f"Following: {response.data.following}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Follow a user -const response = await client.users.follow("123456789", { - targetUserId: "2244994945", -}); -console.log(`Following: ${response.data?.following}`); -``` - - - -### Unfollow a user (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/users/123456789/following/2244994945" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/following/2244994945" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Unfollow a user -response = client.users.unfollow( - source_user_id="123456789", - target_user_id="2244994945" -) -print(f"Following: {response.data.following}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Unfollow a user -const response = await client.users.unfollow("123456789", "2244994945"); -console.log(`Following: ${response.data?.following}`); -``` - - +--- +title: v1 to v2 +sidebarTitle: v1 to v2 +keywords: ["v1.1 to v2 migration", "follows migration", "migrate follows", "standard to v2 follows", "v1 to v2 follows", "migration guide"] + + +--- +import { Button } from '/snippets/button.mdx'; + +#### Manage follows: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST friendships/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create) and [POST friendships/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 manage follows endpoints. + +* **Similarities** + * OAuth 1.0a User Context +* **Differences** + * Endpoint URLs + * App and Project requirements + * HTTP methods + * Request parameters + + + +#### Similarities + +**OAuth 1.0a User Context authentication method** + +Both the endpoint versions support [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 manage follows endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/friendships/create.json + (follow a user) + * POST https://api.x.com/1.1/friendships/destroy.json + (unfollow a user) +* X API v2 endpoint: + * POST https://api.x.com/2/users/:id/following + (follow a user) + * DELETE https://api.x.com/2/users/:source\_user\_id/following/:target\_user\_id + (unfollow a user) + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundam \ No newline at end of file diff --git a/enterprise-api/users/get-affiliates.mdx b/enterprise-api/users/get-affiliates.mdx index de66976f2..17ab21cb0 100644 --- a/enterprise-api/users/get-affiliates.mdx +++ b/enterprise-api/users/get-affiliates.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/affiliates ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-blocking.mdx b/enterprise-api/users/get-blocking.mdx index 8ca0ad36f..090c530b6 100644 --- a/enterprise-api/users/get-blocking.mdx +++ b/enterprise-api/users/get-blocking.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/blocking ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-bookmark-folders.mdx b/enterprise-api/users/get-bookmark-folders.mdx index dfdfbee9c..f58360b6f 100644 --- a/enterprise-api/users/get-bookmark-folders.mdx +++ b/enterprise-api/users/get-bookmark-folders.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks/folders ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-bookmarks-by-folder-id.mdx b/enterprise-api/users/get-bookmarks-by-folder-id.mdx index 98c7e3b07..6f0d421f4 100644 --- a/enterprise-api/users/get-bookmarks-by-folder-id.mdx +++ b/enterprise-api/users/get-bookmarks-by-folder-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks/folders/{folder_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-bookmarks.mdx b/enterprise-api/users/get-bookmarks.mdx index fc3894243..e1367873c 100644 --- a/enterprise-api/users/get-bookmarks.mdx +++ b/enterprise-api/users/get-bookmarks.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-followed-lists.mdx b/enterprise-api/users/get-followed-lists.mdx index 98d9c4a4c..f0f5b1065 100644 --- a/enterprise-api/users/get-followed-lists.mdx +++ b/enterprise-api/users/get-followed-lists.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/followed_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-followers.mdx b/enterprise-api/users/get-followers.mdx index adb2d22c6..99e4e6a7c 100644 --- a/enterprise-api/users/get-followers.mdx +++ b/enterprise-api/users/get-followers.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/followers ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-following.mdx b/enterprise-api/users/get-following.mdx index 2995b7ad4..1f51f23b1 100644 --- a/enterprise-api/users/get-following.mdx +++ b/enterprise-api/users/get-following.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/following ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-liked-posts.mdx b/enterprise-api/users/get-liked-posts.mdx index a56f559e3..7a4f973d8 100644 --- a/enterprise-api/users/get-liked-posts.mdx +++ b/enterprise-api/users/get-liked-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/liked_tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-list-memberships.mdx b/enterprise-api/users/get-list-memberships.mdx index 1935f6b5d..4c8272dc1 100644 --- a/enterprise-api/users/get-list-memberships.mdx +++ b/enterprise-api/users/get-list-memberships.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/list_memberships ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-mentions.mdx b/enterprise-api/users/get-mentions.mdx index 4d089897d..7b2833a73 100644 --- a/enterprise-api/users/get-mentions.mdx +++ b/enterprise-api/users/get-mentions.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/mentions ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-muting.mdx b/enterprise-api/users/get-muting.mdx index dbe6684e6..ef9b9babd 100644 --- a/enterprise-api/users/get-muting.mdx +++ b/enterprise-api/users/get-muting.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/muting ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-my-user.mdx b/enterprise-api/users/get-my-user.mdx index bad7698d8..e8dccb741 100644 --- a/enterprise-api/users/get-my-user.mdx +++ b/enterprise-api/users/get-my-user.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/me ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-owned-lists.mdx b/enterprise-api/users/get-owned-lists.mdx index b3f4c7517..81d220f86 100644 --- a/enterprise-api/users/get-owned-lists.mdx +++ b/enterprise-api/users/get-owned-lists.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/owned_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-pinned-lists.mdx b/enterprise-api/users/get-pinned-lists.mdx index 1d70e9542..680c1fd97 100644 --- a/enterprise-api/users/get-pinned-lists.mdx +++ b/enterprise-api/users/get-pinned-lists.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/pinned_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-posts.mdx b/enterprise-api/users/get-posts.mdx index 7b9b6cfd5..708a5fd42 100644 --- a/enterprise-api/users/get-posts.mdx +++ b/enterprise-api/users/get-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-public-keys-for-multiple-users.mdx b/enterprise-api/users/get-public-keys-for-multiple-users.mdx index 0835ad99c..6dc69d250 100644 --- a/enterprise-api/users/get-public-keys-for-multiple-users.mdx +++ b/enterprise-api/users/get-public-keys-for-multiple-users.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/public_keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-reposts-of-me.mdx b/enterprise-api/users/get-reposts-of-me.mdx index 7a00370b5..3915f215d 100644 --- a/enterprise-api/users/get-reposts-of-me.mdx +++ b/enterprise-api/users/get-reposts-of-me.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/reposts_of_me ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-timeline.mdx b/enterprise-api/users/get-timeline.mdx index 1705bcb91..42791925a 100644 --- a/enterprise-api/users/get-timeline.mdx +++ b/enterprise-api/users/get-timeline.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/timelines/reverse_chronological ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-user-by-id.mdx b/enterprise-api/users/get-user-by-id.mdx index 6ff1b1306..d6eba0f4b 100644 --- a/enterprise-api/users/get-user-by-id.mdx +++ b/enterprise-api/users/get-user-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-user-by-username.mdx b/enterprise-api/users/get-user-by-username.mdx index bcd665927..fc7b48dce 100644 --- a/enterprise-api/users/get-user-by-username.mdx +++ b/enterprise-api/users/get-user-by-username.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/by/username/{username} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-user-public-keys.mdx b/enterprise-api/users/get-user-public-keys.mdx index 804e1cbc7..b20716f9a 100644 --- a/enterprise-api/users/get-user-public-keys.mdx +++ b/enterprise-api/users/get-user-public-keys.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/public_keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-users-by-ids.mdx b/enterprise-api/users/get-users-by-ids.mdx index cbbbf5ce0..9532932b2 100644 --- a/enterprise-api/users/get-users-by-ids.mdx +++ b/enterprise-api/users/get-users-by-ids.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/get-users-by-usernames.mdx b/enterprise-api/users/get-users-by-usernames.mdx index 13887ad74..2eb597ad1 100644 --- a/enterprise-api/users/get-users-by-usernames.mdx +++ b/enterprise-api/users/get-users-by-usernames.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/by ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/like-post.mdx b/enterprise-api/users/like-post.mdx index e6197dc22..004cac235 100644 --- a/enterprise-api/users/like-post.mdx +++ b/enterprise-api/users/like-post.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/likes ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/lookup/integrate.mdx b/enterprise-api/users/lookup/integrate.mdx index 01963ff08..b62378814 100644 --- a/enterprise-api/users/lookup/integrate.mdx +++ b/enterprise-api/users/lookup/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating User lookup keywords: ["user lookup integration", "users integration guide", "user lookup implementation"] --- diff --git a/enterprise-api/users/lookup/migrate/overview.mdx b/enterprise-api/users/lookup/migrate/overview.mdx index a8d9b7018..45aa75c05 100644 --- a/enterprise-api/users/lookup/migrate/overview.mdx +++ b/enterprise-api/users/lookup/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["user lookup migration", "users lookup migration", "v1.1 to v2 user lookup", "user lookup migration guide", "migrate user lookup"] ---- + import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/users/lookup/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/users/lookup/migrate/standard-to-twitter-api-v2.mdx index 4395b6bf6..989a53378 100644 --- a/enterprise-api/users/lookup/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/users/lookup/migrate/standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "user lookup migration", "migrate user lookup", "standard to v2 user lookup", "v1 to v2 user lookup", "migration guide"] ---- + +--- import { Button } from '/snippets/button.mdx'; ### Standard v1.1 compared to X API v2 @@ -34,196 +35,4 @@ The standard v1.1 GET users/lookup endpoint allows you to specify 100 users per #### Differences -**Endpoint URLs** - -* Standard v1.1 endpoints: - * https://api.x.com/1.1/users/show (single-ID or username lookup) - * https://api.x.com/1.1/users/lookup (multi-ID or username lookup) -* X API v2 endpoint: - * https://api.x.com/2/users (multi-ID lookup) - * https://api.x.com/2/users/:id (single-ID lookup) - * https://api.x.com/2/users/by (multi-username lookup) - * https://api.x.com/2/users/by/username/:username (single-username lookup) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the user id , name, and username fields by default. To request any additional fields or objects, you wil need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any user fields that you request from this endpoint will return in the primary user object. Any expanded Post object and fields will return in an includes object within your response. You can then match any expanded objects back to the user object by matching the IDs located in both the user and the expanded Post object. - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. - - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array. -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like. -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values. - - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields -* A new reply_setting field, which shows you who can reply to a given Post - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| | | -| :--- | :--- | -| **Standard** | **X API v2** | -| user_id | ids | -| screen_name | username | - -There are also a set of standard users lookup request parameters **not** supported in X API v2: - -| Standard | Comment | -| :--- | :--- | -| include_entities | This parameter is used to remove the entities node from the Post payload. It has been replaced with the additive fields and expansions functionality. | - ---- - -### Code Examples - -The following examples show standard v1.1 endpoints and their v2 equivalents. - -**Single user lookup: v1.1 `GET users/show` → v2 `GET /users/by/username/:username`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/users/show.json?screen_name=XDevelopers' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/users/by/username/XDevelopers?user.fields=created_at,description,public_metrics' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/users/by/username/XDevelopers" - -params = { - "user.fields": "created_at,description,public_metrics" -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user by username with additional fields -response = client.users.get_by_username( - "XDevelopers", - user_fields=["created_at", "description", "public_metrics"] -) - -print(f"Name: {response.data.name}") -print(f"Followers: {response.data.public_metrics.followers_count}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -const response = await client.users.getByUsername("XDevelopers", { - userFields: ["created_at", "description", "public_metrics"], -}); - -console.log(`Name: ${response.data?.name}`); -console.log(`Followers: ${response.data?.public_metrics?.followers_count}`); -``` - - - -**Multiple users lookup: v1.1 `GET users/lookup` → v2 `GET /users/by`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/users/lookup.json?screen_name=XDevelopers,X,XAPI' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&user.fields=created_at,public_metrics' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/users/by" - -params = { - "usernames": "XDevelopers,X,XAPI", - "user.fields": "created_at,public_metrics" -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -for user in response.json()["data"]: - print(f"{user['username']}: {user['public_metrics']['followers_count']} followers") -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get multiple users by usernames -response = client.users.get_users_by_usernames( - usernames=["XDevelopers", "X", "XAPI"], - user_fields=["created_at", "public_metrics"] -) - -for user in response.data: - print(f"{user.username}: {user.public_metrics.followers_count} followers") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -const response = await client.users.getUsersByUsernames({ - usernames: ["XDevelopers", "X", "XAPI"], - userFields: ["created_at", "public_metrics"], -}); - -response.data?.forEach((user) => { - console.log(`${user.username}: ${user.public_metrics?.followers_count} followers`); -}); -``` - - +**Endpoint URLs \ No newline at end of file diff --git a/enterprise-api/users/mute-user.mdx b/enterprise-api/users/mute-user.mdx index 2700f5d02..a171d6d19 100644 --- a/enterprise-api/users/mute-user.mdx +++ b/enterprise-api/users/mute-user.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/muting ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/mutes/integrate.mdx b/enterprise-api/users/mutes/integrate.mdx index 798ec039b..34f19e60b 100644 --- a/enterprise-api/users/mutes/integrate.mdx +++ b/enterprise-api/users/mutes/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating mutes endpoints keywords: ["mutes integration", "mute users integration", "mutes guide"] --- diff --git a/enterprise-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.mdx b/enterprise-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.mdx index b0cfbeb91..f0711e187 100644 --- a/enterprise-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.mdx +++ b/enterprise-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.mdx @@ -1,195 +1,46 @@ ---- -title: Manage mutes -sidebarTitle: Manage mutes -keywords: ["manage mutes migration", "v1.1 to v2 manage mutes", "migrate manage mutes", "standard to v2 mutes", "mutes migration"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Manage mutes: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST mutes/users/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create) and [POST mutes/users/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage mutes endpoints. - -* **Similarities** - * OAuth 1.0a User Context -* **Differences** - * Endpoint URLs - * App and Project requirements - * HTTP methods - * Request parameters - - -#### Similarities - -**OAuth 1.0a User Context authentication method** - -Both the endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage mutes endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/mutes/users/create.json - (mute a user) - * POST https://api.x.com/1.1/mutes/users/destroy.json - (unmute a user) -* X API v2 endpoint: - * POST https://api.x.com/2/users/:id/muting - (mute a user) - * DELETE https://api.x.com/2/users/:source\_user\_id/muting/:target\_user\_id - (unmute a user) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard v1.1 | X API v2 | -| :--- | :--- | -| user_id | target\_user\_id | -| screen_name | No equivalent | - -Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters (for the POST endpoint) or path parameters (for the DELETE endpoint). - -Also, an id of the user muting a target user is not required when using the standard v1.1 endpoints since the access tokens passed with [OAuth 1.0a User Context](/resources/fundamentals/authentication) inferred which user was initiating the mute/unmute. - ---- - -## Code examples - -### Mute a user (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123456789/muting" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"target_user_id": "2244994945"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/muting" -response = requests.post(url, auth=auth, json={"target_user_id": "2244994945"}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Mute a user -response = client.users.mute( - source_user_id="123456789", - target_user_id="2244994945" -) -print(f"Muting: {response.data.muting}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Mute a user -const response = await client.users.mute("123456789", { - targetUserId: "2244994945", -}); -console.log(`Muting: ${response.data?.muting}`); -``` - - - -### Unmute a user (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/users/123456789/muting/2244994945" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/muting/2244994945" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Unmute a user -response = client.users.unmute( - source_user_id="123456789", - target_user_id="2244994945" -) -print(f"Muting: {response.data.muting}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Unmute a user -const response = await client.users.unmute("123456789", "2244994945"); -console.log(`Muting: ${response.data?.muting}`); -``` - - +--- +title: Manage mutes +sidebarTitle: Manage mutes +keywords: ["manage mutes migration", "v1.1 to v2 manage mutes", "migrate manage mutes", "standard to v2 mutes", "mutes migration"] + + +--- +import { Button } from '/snippets/button.mdx'; + +### Manage mutes: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST mutes/users/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create) and [POST mutes/users/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage mutes endpoints. + +* **Similarities** + * OAuth 1.0a User Context +* **Differences** + * Endpoint URLs + * App and Project requirements + * HTTP methods + * Request parameters + + +#### Similarities + +**OAuth 1.0a User Context authentication method** + +Both the endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage mutes endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/mutes/users/create.json + (mute a user) + * POST https://api.x.com/1.1/mutes/users/destroy.json + (unmute a user) +* X API v2 endpoint: + * POST https://api.x.com/2/users/:id/muting + (mute a user) + * DELETE https://api.x.com/2/users/:source\_user\_id/muting/:target\_user\_id + (unmute a user) + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project \ No newline at end of file diff --git a/enterprise-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.mdx b/enterprise-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.mdx index 1b0ba8db9..9992a6c05 100644 --- a/enterprise-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.mdx +++ b/enterprise-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: Mutes lookup sidebarTitle: Mutes lookup keywords: ["mutes lookup migration", "v1.1 to v2 mutes lookup", "migrate mutes lookup", "standard to v2 mutes", "mutes migration"] ---- + +--- import { Button } from '/snippets/button.mdx'; ### Mutes lookup: Standard v1.1 compared to X API v2 @@ -42,134 +43,4 @@ Both the standard v1.1 and X API v2 mutes lookup endpoints use [OAuth 1.0a User **Users per request limits** -The standard v1.1 endpoints allow you to return up to 5000 users per request. The new v2 endpoints allow you to return up to 1000 users per request. To return a full 1000 users, you will need to pass max_results=1000 as a query parameter; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request. -  - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the user id, name, and username fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any user fields that you request from this endpoint will return in the primary user object. Any expanded Post object and fields will return an includes object within your response. You can then match any expanded objects back to the user object by matching the IDs located in both the user and the expanded Post object.  - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.  -   - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| **Standard** | **X API v2** | -| :--- | :--- | -| stringify_ids | No equivalent | -| cursor | pagination_token | -| skip_status | No equivalent | - -There are also a set of standard v1.1 Mutes lookup request parameters **not** supported in X API v2: - -| Standard | Comment | -| :--- | :--- | -| include_entities | This parameter is used to remove the entities node from the Post payload. It has been replaced with additive fields and expansions functionality. | - ---- - -## Code examples - -### Get muted users (v2) - - - -```bash cURL -curl "https://api.x.com/2/users/123456789/muting?user.fields=username,verified&max_results=100" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/muting" -params = {"user.fields": "username,verified", "max_results": 100} - -response = requests.get(url, auth=auth, params=params) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Get muted users with pagination -for page in client.users.get_muting( - "123456789", - user_fields=["username", "verified"], - max_results=100 -): - for user in page.data: - print(f"{user.username} - Verified: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Get muted users with pagination -const paginator = client.users.getMuting("123456789", { - userFields: ["username", "verified"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((user) => { - console.log(`${user.username} - Verified: ${user.verified}`); - }); -} -``` - - +The standard v1.1 endpoints allow you to return up to 5000 users per request. The new v2 endpoints allow you to return up to 1000 users per request. To return a full 1000 users, you w \ No newline at end of file diff --git a/enterprise-api/users/mutes/migrate/overview.mdx b/enterprise-api/users/mutes/migrate/overview.mdx index 3ad477fb3..f9a505baf 100644 --- a/enterprise-api/users/mutes/migrate/overview.mdx +++ b/enterprise-api/users/mutes/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["mutes migration", "mutes migrate", "v1.1 to v2 mutes", "mutes migration guide", "migrate mutes"] ---- + import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/users/pin-list.mdx b/enterprise-api/users/pin-list.mdx index 06b053043..ea308305f 100644 --- a/enterprise-api/users/pin-list.mdx +++ b/enterprise-api/users/pin-list.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/pinned_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/repost-post.mdx b/enterprise-api/users/repost-post.mdx index 8d6c6bed3..bf5a6462b 100644 --- a/enterprise-api/users/repost-post.mdx +++ b/enterprise-api/users/repost-post.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/retweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/search-users.mdx b/enterprise-api/users/search-users.mdx index 04ae03548..8c735d93e 100644 --- a/enterprise-api/users/search-users.mdx +++ b/enterprise-api/users/search-users.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/search ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/unblock-dms.mdx b/enterprise-api/users/unblock-dms.mdx index 93fa39097..fadadb2b7 100644 --- a/enterprise-api/users/unblock-dms.mdx +++ b/enterprise-api/users/unblock-dms.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/dm/unblock ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/unfollow-list.mdx b/enterprise-api/users/unfollow-list.mdx index f9a9dd506..285a886fa 100644 --- a/enterprise-api/users/unfollow-list.mdx +++ b/enterprise-api/users/unfollow-list.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/followed_lists/{list_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/unfollow-user.mdx b/enterprise-api/users/unfollow-user.mdx index fad80620a..6640aa553 100644 --- a/enterprise-api/users/unfollow-user.mdx +++ b/enterprise-api/users/unfollow-user.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{source_user_id}/following/{target_user_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/unlike-post.mdx b/enterprise-api/users/unlike-post.mdx index 41a1df715..bf0bb9873 100644 --- a/enterprise-api/users/unlike-post.mdx +++ b/enterprise-api/users/unlike-post.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/likes/{tweet_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/unmute-user.mdx b/enterprise-api/users/unmute-user.mdx index 1dca169c7..46e1ce21d 100644 --- a/enterprise-api/users/unmute-user.mdx +++ b/enterprise-api/users/unmute-user.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{source_user_id}/muting/{target_user_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/unpin-list.mdx b/enterprise-api/users/unpin-list.mdx index fc06898f6..7c1b78f1f 100644 --- a/enterprise-api/users/unpin-list.mdx +++ b/enterprise-api/users/unpin-list.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/pinned_lists/{list_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/users/unrepost-post.mdx b/enterprise-api/users/unrepost-post.mdx index 04622dc50..4835d8b14 100644 --- a/enterprise-api/users/unrepost-post.mdx +++ b/enterprise-api/users/unrepost-post.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/retweets/{source_tweet_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/webhooks/create-replay-job-for-webhook.mdx b/enterprise-api/webhooks/create-replay-job-for-webhook.mdx index 914ba7e7f..c6cb52d7e 100644 --- a/enterprise-api/webhooks/create-replay-job-for-webhook.mdx +++ b/enterprise-api/webhooks/create-replay-job-for-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/webhooks/replay ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/webhooks/create-stream-link.mdx b/enterprise-api/webhooks/create-stream-link.mdx index 821d78440..661db4d86 100644 --- a/enterprise-api/webhooks/create-stream-link.mdx +++ b/enterprise-api/webhooks/create-stream-link.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/tweets/search/webhooks/{webhook_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/webhooks/create-webhook.mdx b/enterprise-api/webhooks/create-webhook.mdx index c170a7f50..45e0a0b07 100644 --- a/enterprise-api/webhooks/create-webhook.mdx +++ b/enterprise-api/webhooks/create-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/webhooks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/webhooks/delete-stream-link.mdx b/enterprise-api/webhooks/delete-stream-link.mdx index 7cbe5ff36..3c5ce38ee 100644 --- a/enterprise-api/webhooks/delete-stream-link.mdx +++ b/enterprise-api/webhooks/delete-stream-link.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/tweets/search/webhooks/{webhook_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/webhooks/delete-webhook.mdx b/enterprise-api/webhooks/delete-webhook.mdx index 32abbe065..9c2f9b1f3 100644 --- a/enterprise-api/webhooks/delete-webhook.mdx +++ b/enterprise-api/webhooks/delete-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/webhooks/{webhook_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/webhooks/get-stream-links.mdx b/enterprise-api/webhooks/get-stream-links.mdx index 95bc8e57b..826933a07 100644 --- a/enterprise-api/webhooks/get-stream-links.mdx +++ b/enterprise-api/webhooks/get-stream-links.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/webhooks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/webhooks/get-webhook.mdx b/enterprise-api/webhooks/get-webhook.mdx index 51cec55d2..a686ad9be 100644 --- a/enterprise-api/webhooks/get-webhook.mdx +++ b/enterprise-api/webhooks/get-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/webhooks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/enterprise-api/webhooks/stream/introduction.mdx b/enterprise-api/webhooks/stream/introduction.mdx index eb5d7503a..72ec3bf6d 100644 --- a/enterprise-api/webhooks/stream/introduction.mdx +++ b/enterprise-api/webhooks/stream/introduction.mdx @@ -2,7 +2,8 @@ title: Filtered Stream Webhooks API sidebarTitle: Introduction keywords: ["filtered stream webhooks", "stream webhooks", "webhook stream", "filtered stream webhook", "streaming webhooks", "webhook delivery"] ---- + +description: The filtered stream endpoint group enables developers to filter a stream of public Posts. This endpoint group’s functionality includes multiple endpoint...--- import { Button } from '/snippets/button.mdx'; diff --git a/enterprise-api/webhooks/stream/quickstart.mdx b/enterprise-api/webhooks/stream/quickstart.mdx index 71f965eba..18a795fa8 100644 --- a/enterprise-api/webhooks/stream/quickstart.mdx +++ b/enterprise-api/webhooks/stream/quickstart.mdx @@ -2,7 +2,8 @@ title: Quickstart sidebarTitle: Quickstart keywords: ["filtered stream webhooks quickstart", "webhook stream quickstart", "stream webhooks tutorial", "webhook stream guide"] ---- + +description: The v2 filtered stream webhooks API is similar to the [v2 filtered stream endpoint](/x-api/posts/filtered-stream/introduction) in terms of setting up th...--- ## Getting started with the filtered stream webhooks API diff --git a/enterprise-api/webhooks/validate-webhook.mdx b/enterprise-api/webhooks/validate-webhook.mdx index 952c5b6d0..d858a7b83 100644 --- a/enterprise-api/webhooks/validate-webhook.mdx +++ b/enterprise-api/webhooks/validate-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: put /2/webhooks/{webhook_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/fundamentals/authentication/basic-auth.mdx b/fundamentals/authentication/basic-auth.mdx index 429027354..926d0d196 100644 --- a/fundamentals/authentication/basic-auth.mdx +++ b/fundamentals/authentication/basic-auth.mdx @@ -2,7 +2,8 @@ title: Basic authentication sidebarTitle: Basic authentication keywords: ["basic authentication", "HTTP basic auth", "enterprise authentication", "basic auth", "HTTP authentication", "enterprise API auth"] ---- + +description: Many of X's enterprise APIs require the use of HTTP Basic Authentication. To make a successful request to an API that requires Basic Authentication, you...--- ## Basic authentication diff --git a/fundamentals/authentication/faq.mdx b/fundamentals/authentication/faq.mdx index fae19e28e..c2c65dc7e 100644 --- a/fundamentals/authentication/faq.mdx +++ b/fundamentals/authentication/faq.mdx @@ -2,7 +2,8 @@ title: OAuth FAQ sidebarTitle: FAQ keywords: ["OAuth FAQ", "authentication FAQ", "OAuth questions", "authentication help", "OAuth troubleshooting", "auth FAQ"] ---- + +description: Reference documentation for the OAuth FAQ endpoint and related functionality.--- ## General diff --git a/fundamentals/authentication/guides/authentication-best-practices.mdx b/fundamentals/authentication/guides/authentication-best-practices.mdx index 3c57d928b..a6c0702c8 100644 --- a/fundamentals/authentication/guides/authentication-best-practices.mdx +++ b/fundamentals/authentication/guides/authentication-best-practices.mdx @@ -1,7 +1,8 @@ --- title: Best practices keywords: ["authentication best practices", "OAuth best practices", "security best practices", "API key security", "token security", "auth security"] ---- + +description: Your API keys and tokens should be guarded very carefully. These credentials are directly tied to your [developer App](/resources/fundamentals/developer...--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/guides/log-in-with-x.mdx b/fundamentals/authentication/guides/log-in-with-x.mdx index cb8624250..fbc185bd3 100644 --- a/fundamentals/authentication/guides/log-in-with-x.mdx +++ b/fundamentals/authentication/guides/log-in-with-x.mdx @@ -1,7 +1,8 @@ --- title: Log in with X keywords: ["Log in with X", "Sign in with X", "X login", "OAuth login", "social login", "X authentication", "login integration"] ---- + +description: Use Log in with X, also known as Sign in with X, to place a button on your site or application which allows X users to enjoy the benefits of a registere...--- import { Button } from "/snippets/button.mdx"; @@ -220,13 +221,8 @@ The UI flow for mobile web browsers works exactly like the Browser sign in flow, Below are screenshots for the signed in, signed out, and redirect screens: - - - - - - - + Mobile sign in flow - \ No newline at end of file + + diff --git a/fundamentals/authentication/guides/tls.mdx b/fundamentals/authentication/guides/tls.mdx index 8dafe8388..fe0b95cdb 100644 --- a/fundamentals/authentication/guides/tls.mdx +++ b/fundamentals/authentication/guides/tls.mdx @@ -2,7 +2,8 @@ title: Connection to X API using TLS sidebarTitle: TLS keywords: ["TLS", "SSL", "HTTPS", "secure connection", "TLS connection", "encrypted connection", "API security"] ---- + +description: TLS connections are required in order to access X API endpoints. Communicating over TLS preserves user privacy and security by protecting information be...--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/guides/v2-authentication-mapping.mdx b/fundamentals/authentication/guides/v2-authentication-mapping.mdx index c6f10f106..df2f0b88b 100644 --- a/fundamentals/authentication/guides/v2-authentication-mapping.mdx +++ b/fundamentals/authentication/guides/v2-authentication-mapping.mdx @@ -2,7 +2,8 @@ title: X API v2 authentication mapping sidebarTitle: Endpoint mapping keywords: ["authentication mapping", "v2 authentication", "endpoint mapping", "auth mapping", "v1 to v2 mapping", "authentication guide"] ---- + +description: The following chart illustrates which v2 endpoints map to what authentication methods. | | | | | | :--- | :--- | :--- | :--- | | **Endpoint** | **OAuth 1.--- import { Button } from "/snippets/button.mdx"; @@ -41,8 +42,4 @@ The following chart illustrates which v2 endpoints map to what authentication me | [List Tweets lookup](/x-api/lists/list-tweets/introduction)

Lookup Tweets from a specified List

[GET /2/lists/:id/tweets](/x-api/posts/list-posts-timeline-by-list-id) | ✅ | ✅ | ✅

Scopes:

tweet.read

users.read

list.read | | [List members lookup](/x-api/lists/list-members/introduction#list-members-lookup)

Returns a list of members from a specified List

[GET /2/lists/:id/members](/x-api/users/returns-user-objects-that-are-members-of-a-list-by-the-provided-list-id)

Returns all Lists a specified user is a member of

[GET /2/users/:id/list_memberships](/x-api/lists/get-a-users-list-memberships) | ✅ | ✅ | ✅

Scopes:

tweet.read

users.read

list.read | | [Manage List members](/x-api/lists/list-members/introduction#manage-list-members)

Add a member to a List that the authenticated user owns

[POST /2/lists/:id/members](/x-api/users/returns-user-objects-that-are-members-of-a-list-by-the-provided-list-id)

Removes a member from a List the authenticated user owns

[DELETE /2/lists/:id/members/:user_id](/x-api/lists/remove-a-list-member) | ✅ | | ✅

Scopes:

tweet.read

users.read

list.write | -| [List follows lookup](/x-api/lists/list-lookup/introduction)

Returns all followers of a specified List

[GET /2/lists/:id/followers](/x-api/users/returns-user-objects-that-follow-a-list-by-the-provided-list-id)

Returns all Lists a specified user follows

[GET /2/users/:id/followed_lists](/x-api/lists/get-users-followed-lists) | ✅ | ✅ | ✅

Scopes:

tweet.read

users.read

list.read | -| [Manage List follows](/x-api/lists/manage-lists/introduction)

Follows a List on behalf of an authenticated user

[POST /2/users/:id/followed_lists](/x-api/lists/follow-a-list)

Unfollows a List on behalf of an authenticated user

[DELETE /2/users/:id/followed\_lists/:list\_id](/x-api/lists/unfollow-a-list) | ✅ | | ✅

Scopes:

tweet.read

users.read

list.write | -| [Pinned List lookup](/x-api/lists/pinned-lists/introduction)

Returns the pinned Lists of the authenticated user

[GET /2/users/:id/pinned_lists](/x-api/lists/get-a-users-pinned-lists) | ✅ | | ✅

Scopes:

tweet.read

users.read

list.read | -| [Manage pinned List](/x-api/lists/pinned-lists/introduction)

Pins a List on behalf of an authenticated user

[POST /2/users/:id/pinned_lists](/x-api/lists/pin-a-list)

Unpins a List on behalf of an authenticated user

[DELETE /2/users/:id/pinned\_lists/:list\_id](/x-api/lists/unpin-a-list) | ✅ | | ✅

Scopes:

tweet.read

users.read

list.write | -| [Batch compliance](/x-api/compliance/batch-compliance/introduction)

Creates a new compliance job

[POST /2/compliance/jobs](/x-api/compliance/create-compliance-job)

Returns status and download information about a specified compliance job

[GET /2/compliance/jobs/:job_id](/x-api/compliance/get-compliance-job)

Returns a list of recent compliance jobs

[GET /2/compliance/jobs](/x-api/compliance/list-compliance-jobs) | | ✅ | | +| [List follows lookup](/x-api/lists/list-lookup/introduction)

Returns all followers of a specified List

[GET /2/lists/:id/followers](/x-api/users/returns-user-objects-that-follow-a-list-by-the-provided-list-id)

Returns all Lists a specified user follows

[GET /2/users/:id/followed_lists](/x-api/lists/get-users-followed-lists) | ✅ | ✅ | ✅

Scope \ No newline at end of file diff --git a/fundamentals/authentication/oauth-1-0a/api-key-and-secret.mdx b/fundamentals/authentication/oauth-1-0a/api-key-and-secret.mdx index bca8121fc..b57d788de 100644 --- a/fundamentals/authentication/oauth-1-0a/api-key-and-secret.mdx +++ b/fundamentals/authentication/oauth-1-0a/api-key-and-secret.mdx @@ -2,7 +2,8 @@ title: API Key and Secret sidebarTitle: API Key and Secret keywords: ["API key", "API secret", "consumer key", "consumer secret", "OAuth 1.0a keys", "API credentials", "developer keys"] ---- + +description: The API Key and Secret (also known as Consumer Key and Secret) are the most fundamental credentials required to access the X API. These credentials act ...--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/oauth-1-0a/authorizing-a-request.mdx b/fundamentals/authentication/oauth-1-0a/authorizing-a-request.mdx index 82202bf1e..7556fb3b6 100644 --- a/fundamentals/authentication/oauth-1-0a/authorizing-a-request.mdx +++ b/fundamentals/authentication/oauth-1-0a/authorizing-a-request.mdx @@ -2,7 +2,8 @@ title: Authorizing a request sidebarTitle: Authorizing a request keywords: ["authorize request", "OAuth authorization", "request authorization", "OAuth 1.0a authorization", "authorize API request"] ---- + +description: The purpose of this document is to show you how to modify HTTP requests for the purpose of sending authorized requests to the X API. All of X's APIs are...--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/oauth-1-0a/creating-a-signature.mdx b/fundamentals/authentication/oauth-1-0a/creating-a-signature.mdx index 193ce0902..7f40611a2 100644 --- a/fundamentals/authentication/oauth-1-0a/creating-a-signature.mdx +++ b/fundamentals/authentication/oauth-1-0a/creating-a-signature.mdx @@ -2,7 +2,8 @@ title: Creating a signature sidebarTitle: Creating a signature keywords: ["OAuth signature", "create signature", "OAuth 1.0a signature", "HMAC signature", "signature generation", "OAuth signing"] ---- + +description: This page explains how to generate an OAuth 1. 0a HMAC-SHA1 signature for an HTTP request.--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/oauth-1-0a/oauth-echo.mdx b/fundamentals/authentication/oauth-1-0a/oauth-echo.mdx index 86b22371f..c22a0bdaf 100644 --- a/fundamentals/authentication/oauth-1-0a/oauth-echo.mdx +++ b/fundamentals/authentication/oauth-1-0a/oauth-echo.mdx @@ -2,7 +2,8 @@ title: OAuth Echo sidebarTitle: OAuth Echo keywords: ["OAuth echo", "OAuth echo test", "OAuth verification", "echo test", "OAuth 1.0a echo", "verify OAuth"] ---- + +description: OAuth Echo is a means to securely delegate OAuth authorization with a third party while interacting with an API. There are four parties involved in this...--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens.mdx b/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens.mdx index 0e8a533f3..4a2f42505 100644 --- a/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens.mdx +++ b/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens.mdx @@ -2,7 +2,8 @@ title: Obtaining Access Tokens using 3-legged OAuth flow sidebarTitle: User Access Tokens (3-legged OAuth flow) keywords: ["3-legged OAuth", "user access tokens", "OAuth flow", "obtain access tokens", "OAuth 1.0a flow", "access token generation"] ---- + +description: To perform actions on behalf of another user, you'll need to obtain their access tokens. Access tokens specify the X account the request is made on beha...--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/oauth-1-0a/overview.mdx b/fundamentals/authentication/oauth-1-0a/overview.mdx index 3c3b12053..44b196954 100644 --- a/fundamentals/authentication/oauth-1-0a/overview.mdx +++ b/fundamentals/authentication/oauth-1-0a/overview.mdx @@ -2,7 +2,8 @@ title: OAuth 1.0a sidebarTitle: Overview keywords: ["OAuth 1.0a", "OAuth 1.0", "OAuth 1.0a authentication", "OAuth 1.0a user context", "three-legged OAuth", "OAuth 1.0a flow"] ---- + +description: Many endpoints on the X developer platform use the OAuth 1. 0a method to act, or make API requests, on behalf of a X account.--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters.mdx b/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters.mdx index 5ccb00ab8..2f2c2f2d6 100644 --- a/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters.mdx +++ b/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters.mdx @@ -2,7 +2,8 @@ title: Percent encoding parameters sidebarTitle: Percent encoding parameters keywords: ["percent encoding", "URL encoding", "OAuth encoding", "parameter encoding", "URL encode", "OAuth 1.0a encoding"] ---- + +description: Parts of the X API, particularly those dealing with OAuth signatures, require strings to be encoded according to [RFC 3986, Section 2. 1](http://tools.--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/oauth-1-0a/pin-based-oauth.mdx b/fundamentals/authentication/oauth-1-0a/pin-based-oauth.mdx index 16d96c9f5..17c386f6f 100644 --- a/fundamentals/authentication/oauth-1-0a/pin-based-oauth.mdx +++ b/fundamentals/authentication/oauth-1-0a/pin-based-oauth.mdx @@ -2,7 +2,8 @@ title: PIN-based authorization sidebarTitle: PIN-based OAuth keywords: ["PIN-based OAuth", "PIN OAuth", "OAuth PIN", "PIN authorization", "OAuth 1.0a PIN", "desktop OAuth"] ---- + +description: The PIN-based OAuth flow is a version of the [3-legged OAuth](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) process an...--- import { Button } from "/snippets/button.mdx"; diff --git a/fundamentals/authentication/oauth-2-0/application-only.mdx b/fundamentals/authentication/oauth-2-0/application-only.mdx index 75030be78..623eb89d1 100644 --- a/fundamentals/authentication/oauth-2-0/application-only.mdx +++ b/fundamentals/authentication/oauth-2-0/application-only.mdx @@ -2,6 +2,8 @@ title: App only authentication and OAuth 2.0 Bearer Token sidebarTitle: OAuth 2.0 App-Only (Bearer Token) keywords: ["app-only authentication", "OAuth 2.0 app-only", "Bearer Token authentication", "app-only auth", "read-only access", "public data access"] + + --- ### App only authentication and OAuth 2.0 Bearer Token diff --git a/fundamentals/authentication/oauth-2-0/authorization-code.mdx b/fundamentals/authentication/oauth-2-0/authorization-code.mdx index a567583f6..40a6167b6 100644 --- a/fundamentals/authentication/oauth-2-0/authorization-code.mdx +++ b/fundamentals/authentication/oauth-2-0/authorization-code.mdx @@ -2,7 +2,8 @@ title: OAuth 2.0 Authorization Code Flow with PKCE sidebarTitle: OAuth 2.0 Authorization Code Flow with PKCE keywords: ["OAuth 2.0 PKCE", "authorization code flow", "PKCE", "OAuth 2.0 flow", "PKCE flow", "OAuth 2.0 authorization", "code challenge"] ---- + +description: 0 is an industry-standard authorization protocol that allows for greater control over an application’s scope, and authorization flows across multiple de...--- ### OAuth 2.0 Authorization Code Flow with PKCE #### Introduction diff --git a/fundamentals/authentication/oauth-2-0/bearer-tokens.mdx b/fundamentals/authentication/oauth-2-0/bearer-tokens.mdx index ddd0f6ec3..ed6f59bfd 100644 --- a/fundamentals/authentication/oauth-2-0/bearer-tokens.mdx +++ b/fundamentals/authentication/oauth-2-0/bearer-tokens.mdx @@ -2,7 +2,8 @@ title: Using and generating an app-only Bearer Token sidebarTitle: Generating and using app-only Bearer Tokens keywords: ["Bearer token", "app-only token", "Bearer Token", "OAuth 2.0 Bearer", "app authentication", "generate Bearer token"] ---- + +description: A bearer token allows developers to have a more secure point of entry for using the X APIs, and are one of the core features of OAuth 2.--- ### Using and generating an app-only Bearer Token diff --git a/fundamentals/authentication/oauth-2-0/overview.mdx b/fundamentals/authentication/oauth-2-0/overview.mdx index 21b6afc81..68de9ac9c 100644 --- a/fundamentals/authentication/oauth-2-0/overview.mdx +++ b/fundamentals/authentication/oauth-2-0/overview.mdx @@ -2,7 +2,8 @@ title: OAuth 2.0 sidebarTitle: Overview keywords: ["OAuth 2.0", "OAuth 2.0 authentication", "OAuth 2.0 PKCE", "Bearer token", "app-only auth", "OAuth 2.0 flow", "authorization code"] ---- + +description: 0 Bearer Token authenticates requests on behalf of your [developer App](/resources/fundamentals/developer-apps).--- ### Bearer Token (also known as app-only) diff --git a/fundamentals/authentication/oauth-2-0/user-access-token.mdx b/fundamentals/authentication/oauth-2-0/user-access-token.mdx index 52d361156..cbe7d9f67 100644 --- a/fundamentals/authentication/oauth-2-0/user-access-token.mdx +++ b/fundamentals/authentication/oauth-2-0/user-access-token.mdx @@ -2,7 +2,8 @@ title: How to connect to endpoints using OAuth 2.0 Authorization Code Flow with PKCE sidebarTitle: OAuth 2.0 Making requests on behalf of users keywords: ["OAuth 2.0 user access token", "user access token", "OAuth 2.0 user context", "user authentication", "OAuth 2.0 user", "access token"] ---- + +description: To authenticate your users, your App will need to implement an authorization flow. This authorization flow lets you direct your users to an authorizatio...--- ### How to connect to endpoints using OAuth 2.0 Authorization Code Flow with PKCE diff --git a/fundamentals/authentication/overview.mdx b/fundamentals/authentication/overview.mdx index 2c994ce39..acb3453be 100644 --- a/fundamentals/authentication/overview.mdx +++ b/fundamentals/authentication/overview.mdx @@ -2,7 +2,8 @@ title: Authentication sidebarTitle: Overview keywords: ["authentication", "OAuth", "OAuth 1.0a", "OAuth 2.0", "API authentication", "bearer token", "access tokens", "API keys", "user context", "app only", "PKCE", "authorization code", "basic authentication"] ---- + +description: X APIs handle enormous amounts of data. The way we ensure this data is secured for developers and users alike is through authentication.--- import { Button } from "/snippets/button.mdx"; diff --git a/llms.txt b/llms.txt new file mode 100644 index 000000000..dfef24f89 --- /dev/null +++ b/llms.txt @@ -0,0 +1,38 @@ +# X Developer Platform + +> Build, analyze, and innovate with X's real-time, global data and APIs. Comprehensive documentation for the X API v2, Ads API, Enterprise APIs (Account Activity, X Activity, GNIP/PowerTrack), official SDKs, tutorials, and AI-agent tools (llms.txt, skill.md, MCP). + +## Start Here + +- [Overview](https://docs.x.com/overview.md): Introduction to the X Developer Platform +- [Getting Access & First Request](https://docs.x.com/make-your-first-request.md): Quickstart for new developers +- [What to Build](https://docs.x.com/what-to-build.md): Use-case ideas and inspiration +- [Developer Guidelines & Policies](https://docs.x.com/developer-guidelines.md): Rules for building responsibly +- [AI & Agent Resources](https://docs.x.com/tools/ai.md): llms.txt, skill.md, MCP, and Grok/Cursor integration + +## Major Documentation Areas (Nested Indexes) + +- [X API v2 — Full Index](https://docs.x.com/x-api/llms.txt): 370+ reference pages (Posts, Users, DMs, Lists, Spaces, Streams, Compliance, Webhooks, Media, etc.) +- [Enterprise APIs — Full Index](https://docs.x.com/enterprise-api/llms.txt): Account Activity, X Activity (XAA), Compliance, Chat, Communities, Direct Messages, News, Trends, Webhooks, and historical GNIP/PowerTrack +- [Ads API — Full Index](https://docs.x.com/x-ads-api/llms.txt): Campaign management, creatives, audiences, analytics, measurement, and conversions +- [SDKs (XDKs) — Full Index](https://docs.x.com/xdks/llms.txt): Python + TypeScript/JavaScript SDK clients, models, and references +- [Python XDK Detail](https://docs.x.com/xdks/python/llms.txt) · [TypeScript XDK Detail](https://docs.x.com/xdks/typescript/llms.txt) + +## Key Fundamentals & Tools + +- [X API Fundamentals](https://docs.x.com/x-api/fundamentals/data-dictionary.md): Fields, expansions, pagination, versioning, consistency, rate limits +- [Authentication Guides](https://docs.x.com/fundamentals/authentication/overview.md): OAuth 1.0a, OAuth 2.0, Bearer tokens, app-only, user context +- [Tools & Libraries](https://docs.x.com/tools-and-libraries.md): Official SDKs, Postman, twurl, xurl +- [Changelog](https://docs.x.com/changelog.md): Platform updates and new endpoints +- [Tutorials](https://docs.x.com/tutorials.md): In-depth code examples and integration guides + +## For AI Agents & LLMs + +- [AGENTS.md](https://docs.x.com/AGENTS.md) / [AGENT.md](https://docs.x.com/AGENT.md): Explicit instructions for AI agents on how to best use this documentation +- [llms-full.txt](https://docs.x.com/llms-full.txt): Entire documentation set as a single Markdown file (maximum context) +- [Raw Markdown for any page](https://docs.x.com/tools/llms-txt.md): Append `.md` to any docs.x.com URL +- [skill.md](https://docs.x.com/tools/skill-md.md): Structured capability summary (agentskills.io) +- [MCP Server](https://docs.x.com/tools/mcp.md): Model Context Protocol server for X API tools + docs search +- [OpenAPI Specification](https://docs.x.com/openapi.json): Machine-readable contract + +All pages are also available under `/.well-known/llms.txt`. Every documentation page supports the `.md` suffix for clean Markdown retrieval by agents. diff --git a/status.mdx b/status.mdx index ffa1c66b1..340b6acfb 100644 --- a/status.mdx +++ b/status.mdx @@ -1,5 +1,6 @@ --- title: X Developer Platform Status +description: Live status of the X API v2, Enterprise APIs, Ads API, streaming endpoints, and all supporting services. Includes current incidents and historical uptime. keywords: ["status", "API status", "system status", "uptime", "service status", "platform status", "operational status", "incidents", "incident history", "outages", "service issues", "API incidents", "system status", "downtime"] --- diff --git a/tools/ai.mdx b/tools/ai.mdx index ff2364b7b..47038cbfb 100644 --- a/tools/ai.mdx +++ b/tools/ai.mdx @@ -13,14 +13,9 @@ Resources for connecting AI tools to the X API and its documentation. Give your AI agent the ability to call X API endpoints directly. - - - XMCP exposes 200+ X API endpoints as callable MCP tools. Docs MCP lets agents search these docs. - - - Machine-readable API definition for auto-generating clients or feeding into agents. - - +**MCP Servers** — XMCP exposes 200+ X API endpoints as callable MCP tools. Docs MCP lets agents search and read these docs on the fly. + +**OpenAPI Spec** — Machine-readable API definition (https://api.x.com/2/openapi.json) for auto-generating clients or feeding into agents. | Resource | What it does | URL | |:---------|:------------|:----| @@ -33,17 +28,11 @@ Give your AI agent the ability to call X API endpoints directly. Give your AI agent context on how the X API works. - - - Documentation index and full-content files for LLMs to ingest. - - - Capability summary that tells agents what actions are possible with the X API. - - - Search and read documentation pages from your AI assistant via MCP. - - +**llms.txt / llms-full.txt** — Documentation index and full-content Markdown files for LLMs to ingest. + +**skill.md** — Capability summary (agentskills.io) that tells agents exactly what actions, parameters, and constraints exist. + +**Docs MCP** — Search and read any documentation page directly from your AI assistant via MCP. | Resource | What it does | URL | |:---------|:------------|:----| diff --git a/tools/llms-txt.mdx b/tools/llms-txt.mdx index 2674a18f4..1624ac42d 100644 --- a/tools/llms-txt.mdx +++ b/tools/llms-txt.mdx @@ -5,28 +5,29 @@ description: Machine-readable documentation files that let AI tools index and un keywords: ["llms.txt", "llms-full.txt", "LLM", "AI tools", "documentation index", "machine-readable", "Grok", "Cursor", "Windsurf"] --- - - - A structured index of all documentation pages. Gives AI tools a map of what's available. - - - The complete documentation in a single Markdown file. Full context for any AI tool. - - +**llms.txt** — A structured index of all documentation pages (titles, URLs, short descriptions). Gives AI tools a map of what's available. + +**llms-full.txt** — The complete documentation in a single Markdown file for maximum context. The [`llms.txt` standard](https://llmstxt.org) is like a sitemap for AI. It helps LLMs understand your documentation structure and find relevant content — similar to how `sitemap.xml` helps search engines. | File | What it contains | Best for | |:-----|:-----------------|:---------| -| [`llms.txt`](https://docs.x.com/llms.txt) | Page titles, URLs, and descriptions | Quick overview, navigation, finding specific topics | -| [`llms-full.txt`](https://docs.x.com/llms-full.txt) | All documentation content in one file | Full context, comprehensive answers, deep understanding | +| [`llms.txt`](https://docs.x.com/llms.txt) | Curated root index + links to section indexes | Quick overview and agent entry point | +| [`x-api/llms.txt`](https://docs.x.com/x-api/llms.txt) | 370+ X API v2 reference pages | Posts, Users, DMs, Streams, Compliance, etc. | +| [`enterprise-api/llms.txt`](https://docs.x.com/enterprise-api/llms.txt) | Enterprise, Account Activity, GNIP, Webhooks | Historical + real-time enterprise data | +| [`x-ads-api/llms.txt`](https://docs.x.com/x-ads-api/llms.txt) | Ads API (campaigns, creatives, audiences, analytics) | Advertising and measurement | +| [`xdks/python/llms.txt`](https://docs.x.com/xdks/python/llms.txt) + [`xdks/typescript/llms.txt`](https://docs.x.com/xdks/typescript/llms.txt) | Full SDK client & model references | Python and TypeScript/JavaScript developers | +| [`llms-full.txt`](https://docs.x.com/llms-full.txt) | Entire docs as one Markdown file | Maximum context for deep reasoning | -These files are also available at `/.well-known/llms.txt` and `/.well-known/llms-full.txt` for tools that follow the `.well-known` convention. Every page in the documentation can be fetched as raw Markdown by appending `.md` to its URL (e.g., `https://docs.x.com/tools/llms-txt.md`). +These files (plus section-specific indexes under `/x-api/llms.txt`, `/enterprise-api/llms.txt`, `/x-ads-api/llms.txt`, and the XDKs) are available at the root and under `/.well-known/`. Every documentation page supports the `.md` suffix for clean Markdown (example: `https://docs.x.com/x-api/posts/get-post-by-id.md`). --- ## How to use it +**Strongly recommended for agents:** Start by reading [AGENTS.md](https://docs.x.com/AGENTS.md) (or AGENT.md) for explicit usage guidance. + Most AI tools accept URLs directly. Just provide the URL and the tool will fetch and parse the content: - **Grok**: Paste `https://docs.x.com/llms-full.txt` into the chat and ask questions about the X API diff --git a/tools/skill-md.mdx b/tools/skill-md.mdx index 0625295ae..6f44de0ae 100644 --- a/tools/skill-md.mdx +++ b/tools/skill-md.mdx @@ -5,10 +5,6 @@ description: A capability summary that tells AI agents what they can do with the keywords: ["skill.md", "agent skills", "AI agent", "agentskills.io", "capability summary", "machine-readable"] --- - - The live skill.md file for the X API documentation. - - The [`skill.md`](https://docs.x.com/skill.md) file follows the [agentskills.io specification](https://agentskills.io/specification) and describes what AI agents can *do* with the X API. While [`llms.txt`](/tools/llms-txt) is a directory of pages, `skill.md` is a capability summary — it lists specific actions, required inputs, and constraints so agents can use the API more reliably. --- diff --git a/x-ads-api/analytics.mdx b/x-ads-api/analytics.mdx index 5b3ca28ef..f1853e686 100644 --- a/x-ads-api/analytics.mdx +++ b/x-ads-api/analytics.mdx @@ -1,5 +1,6 @@ --- title: Analytics +description: Retrieve detailed performance metrics for X ad campaigns, line items, and creatives — including impressions, engagements, video views, and spend via synchronous and asynchronous endpoints. keywords: ["advertising analytics", "ads analytics", "campaign analytics", "ad metrics", "advertising metrics", "campaign performance"] --- import { Button } from '/snippets/button.mdx'; @@ -1076,7 +1077,7 @@ Retrieve reach and average frequency analytics for specified campaigns. | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | campaign_ids
_required_ | Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 20 IDs may be provided.

**Note**: Up to 20 campaign IDs may be provided.

Type: string

Example: `8fgzf` | | end_time
_required_ | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-26T07:00:00Z` | | start_time
_required_ | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-19T07:00:00Z` | @@ -1122,7 +1123,7 @@ Retrieve reach and average frequency analytics for specified funding instruments | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | funding\_instrument\_ids
_required_ | Scope the response to just the desired funding instruments by specifying a comma-separated list of identifiers. Up to 20 IDs may be provided.

**Note**: Up to 20 funding instrument IDs may be provided.

Type: string

Example: `lygyi` | | end_time
_required_ | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-26T07:00:00Z` | | start_time
_required_ | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-19T07:00:00Z` | @@ -1176,7 +1177,7 @@ Retrieve synchronous analytics for the current account. A maximum time range (`e | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | end_time
_required_ | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-26T07:00:00Z` | | entity
_required_ | The entity type to retrieve data for.

Type: enum

Possible values: `ACCOUNT`, `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `ORGANIC_TWEET`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET`, `MEDIA_CREATIVE` | | entity_ids
_required_ | The specific entities to retrieve data for. Specify a comma-separated list of entity IDs.

**Note**: Up to 20 entity IDs may be provided.

Type: string

Example: `8u94t` | @@ -1282,7 +1283,7 @@ Change events are available in hourly buckets. | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | end_time
_required_ | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-26T07:00:00Z` | | entity
_required_ | The entity type to retrieve data for.

Type: enum

Possible values: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `MEDIA_CREATIVE`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET` | | start_time
_required_ | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-19T07:00:00Z` | diff --git a/x-ads-api/audiences.mdx b/x-ads-api/audiences.mdx index a572a85b2..f73aca511 100644 --- a/x-ads-api/audiences.mdx +++ b/x-ads-api/audiences.mdx @@ -1,5 +1,6 @@ --- title: Audiences +description: Create and manage Tailored Audiences and Custom Audiences using CRM lists, website visitors, mobile app users, or engagement data for precise ad targeting. keywords: ["custom audiences", "tailored audiences", "audience targeting", "audience management", "ad targeting", "audience API"] --- import { Button } from '/snippets/button.mdx'; @@ -632,7 +633,7 @@ Please note that results are scoped by a single geo (country). | keywords
_required_ | A comma-separated string of keywords to narrow search by. All keywords are OR'ed with one another.

**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.

Type: string

Example: `developers` | | start_time
_required_ | Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

Type: string

Example: `2017-07-10T00:00:00Z` | | end_time
_optional_ | Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Defaults to the current time.

Type: string

Example: `2017-07-11T00:00:00Z` | -| location
_optional_ | A targeting value you would get from the [GET targeting_criteria/locations](/x-ads-api/campaign-management#get-targeting-criteria-locations) endpoint to narrow results in terms of where the user of the account is located. Note that at present only country level locations are supported.

Type: string

Example: `0ce8b9a7b2742f7e` | +| location
_optional_ | A targeting value you would get from the [GET targeting_criteria/locations](/x-ads-api/campaign-management/reference#get-targeting-criteria-locations) endpoint to narrow results in terms of where the user of the account is located. Note that at present only country level locations are supported.

Type: string

Example: `0ce8b9a7b2742f7e` | | negative_keywords
_optional_ | A comma-separated string of keywords to exclude. All negative keywords are OR'ed with one another.

**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.

Type: string

Example: `rain` | **Example Request[](#example-request "Permalink to this headline")** @@ -712,7 +713,7 @@ Retrieve details for some or all permissions associated with the specified tailo | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | tailored\_audience\_id
_required_ | A reference to the tailored audience you are operating with in the request.

Type: string

Example: `1nmth` | | 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | @@ -765,7 +766,7 @@ Create a new permission object allowing the specified audience to be shared with | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | granted\_account\_id
_required_ | The account you wish to grant the tailored audience permissions for.

Type: string

Example: `18ce54aymz3` | | permission_level
_required_ | The type of access to the tailored audience that the `granted_account_id` should have.

Type: enum

Possible values: `READ_ONLY`, `READ_WRITE` | | tailored\_audience\_id
_required_ | A reference to the tailored audience you are operating with in the request.

Type: string

Example: `2906h` | @@ -813,7 +814,7 @@ When revoked, we guarantee that the granted account (`granted_account_id`) will | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | tailored\_audience\_id
_required_ | A reference to the tailored audience you are operating with in the request.

Type: string

Example: `1nmth` | | tailored\_audience\_permission_id
_required_ | A reference to the tailored audience permission you are operating with in the request.

Type: string

Example: `ri` | @@ -853,7 +854,7 @@ Retrieve a list of active or all line items and campaigns that target a given `c | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | | with_active
_optional_ | When `false`, includes line items that have `servable=false` status

Type: boolean

Default: `true`
Possible values: `true`, `false` | | cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | @@ -1053,7 +1054,7 @@ Retrieve details for some or all permissions associated with the specified custo | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `1nmth` | | 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | @@ -1105,7 +1106,7 @@ Create a new permission object allowing the specified audience to be shared with | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | granted\_account\_id
_required_ | The account you wish to grant the custom audience permissions for.

Type: string

Example: `18ce54aymz3` | | permission_level
_required_ | The type of access to the custom audience that the `granted_account_id` should have.

Type: enum

Possible values: `READ_ONLY`, `READ_WRITE` | | custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | @@ -1154,7 +1155,7 @@ When revoked, we guarantee that the granted account (`granted_account_id`) will | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `1nmth` | | custom\_audience\_permission_id
_required_ | A reference to the custom audience permission you are operating with in the request.

Type: string

Example: `ri` | @@ -1201,7 +1202,7 @@ Retrieve details for some or all Custom Audiences associated with the current ac | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | | permission_scope
_optional_ | Allows filtering the response to lists you own or lists that have been shared with you. By default, without specifying this parameter you will only see audiences you own.

Type: enum

Default: `OWNER`
Possible values: `OWNER`, `SHARED` | @@ -1262,7 +1263,7 @@ Retrieve specific Custom Audiences associated with the current account. | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | | with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | @@ -1312,7 +1313,7 @@ Create a new placeholder Custom Audience associated with the current account. | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | name
_required_ | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.

Type: string

Example: `ads api users` | | description
_optional_ | A description for this audience.

Type: string

Example: `Collection of all users of the Ads API` | @@ -1365,7 +1366,7 @@ Update the specfic Custom Audience associated with the current account. | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | custom\_audience\_id
_required_ | A reference to the Custom Audience you are operating with in the request

Type: string

Example: `2906h` | | name
_optional_ | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.

Type: string

Example: `ads api users` | | description
_optional_ | A description for this audience.

Type: string

Example: `Collection of all users of the Ads API` | @@ -1445,7 +1446,7 @@ Batch API responses return an ordered collection of items. Otherwise, they are i | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | audience_type
_required_ | The type of audience to create.

Type: enum

Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE` | | child_segments
_required_ | An array containing objects which define the subset of a Custom Audience's members that you would like to target. Each object should contain a `custom_audience_id`, `frequency`, `frequency_comparator`, `lookback_window`, `negate`, and, in some cases, additional `child_segments`.

Type: array | | name
_required_ | The display name for the audience. Unique name value must be used. Failure to do so will result in an error.

Type: string

Example: `my_flexible_audience_name` | @@ -1648,7 +1649,7 @@ Delete the specified Custom Audience belonging to the current account. | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | **Example Request[](#example-request "Permalink to this headline")** @@ -1708,7 +1709,7 @@ Retrieve details for some or all Do Not Reach List associated with the current a | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | **Example Request[](#example-request "Permalink to this headline")** @@ -1755,7 +1756,7 @@ Create a new Do Not Reach List associated with the current account. | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | description
_optional_ | A description for this audience.

Type: string

Example: `A list of users to exclude` | **Example Request[](#example-request "Permalink to this headline")** @@ -1826,7 +1827,7 @@ The response returned by the Ads API contains two fields, a `success_count` and | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | do\_not\_reach\_list\_id
_required_ | A reference to the Do Not Reach List you are operating with in the request

Type: string

Example: `2906h` | | operation_type
_required_ | The per `users` group operation type being performed.

Type: enum

Possible values: `Update`, `Delete` | | params
_required_ | A JSON object containing the `emails` array and `expires_at` timestamp.

Type: JSON | diff --git a/x-ads-api/campaign-management.mdx b/x-ads-api/campaign-management.mdx index fc9cafc2a..99ab59741 100644 --- a/x-ads-api/campaign-management.mdx +++ b/x-ads-api/campaign-management.mdx @@ -1,10 +1,23 @@ --- title: Campaign Management sidebarTitle: Overview -keywords: ["campaign management", "ad campaigns", "campaign API", "manage campaigns", "advertising campaigns", "campaign automation"] +description: Create, manage, and optimize advertising campaigns on X. Define budgets, targeting, creatives, and bidding strategies using the Ads API. +keywords: ["campaign management", "ads api", "line items", "ad groups", "promoted ads", "advertising campaigns", "x ads", "campaign api"] --- + import { Button } from '/snippets/button.mdx'; +**Programmatically create, schedule, and manage ad campaigns on X.** + +Campaigns define your budget and schedule. Line items (also called ad groups) control targeting, bidding, and the creatives that run within a campaign. + +## Quick Links + +- [What Can You Promote?](#what-can-you-promote) +- [Creating a Campaign – Step by Step](#creating-a-campaign---step-by-step) +- [Guides](#guides) +- [Full API Reference](/x-ads-api/campaign-management/reference) — All endpoints, parameters, and examples for Accounts, Campaigns, Line Items, Funding Instruments, Targeting, and more. + ## Advertiser API Programatically schedule campaigns and manage ads on X through this suite of APIs. @@ -77,7 +90,7 @@ twurl -H ads-api.x.com /9/accounts/ 2. **Retrieve the funding instrument id.** -Hit the [GET accounts/:account_id/funding_instruments](/x-ads-api/campaign-management#get-accounts-account-id-funding-instruments) API using the account id retrieved in the previous command. +Hit the [GET accounts/:account_id/funding_instruments](/x-ads-api/campaign-management/reference#get-accounts-account-id-funding-instruments) API using the account id retrieved in the previous command. ``` twurl -H ads-api.x.com /9/accounts/xxxxxx/funding_instruments ``` @@ -363,7 +376,7 @@ Mobile app promotion campaigns are required to contain either the `APP_ENGAGEMEN Funding Instruments are the source of campaign budget. Funding Instruments can not be created via the Ads API, they have to be already established by the advertiser’s account manager at X (for credit lines) or via ads.x.com (for credit cards) to be available. -To get a list of all `funding_instruments` on an account, see [GET accounts/:account\_id/funding\_instruments](/x-ads-api/campaign-management#get-accounts-account-id-funding-instruments) and [GET accounts/:account\_id/funding\_instruments/:funding\_instrument\_id](/x-ads-api/campaign-management#get-accounts-account-id-funding-instruments-funding-instrument-id) for the details of a specific one. +To get a list of all `funding_instruments` on an account, see [GET accounts/:account\_id/funding\_instruments](/x-ads-api/campaign-management/reference#get-accounts-account-id-funding-instruments) and [GET accounts/:account\_id/funding\_instruments/:funding\_instrument\_id](/x-ads-api/campaign-management/reference#get-accounts-account-id-funding-instruments-funding-instrument-id) for the details of a specific one. #### Funding Instrument Attributes @@ -444,16 +457,16 @@ The only thing particular about this funding instrument is the type and the fact For more information on Funding Instrument enumerations, please click [here](/x-ads-api/introduction). ### Targeting -Targeting is a core concept of the Ads API. Targeting is set at the line item level and options vary across placements. To set new targeting criteria you need to use [POST accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#post-accounts-account-id-targeting-criteria) and [PUT accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) to update them. +Targeting is a core concept of the Ads API. Targeting is set at the line item level and options vary across placements. To set new targeting criteria you need to use [POST accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#post-accounts-account-id-targeting-criteria) and [PUT accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#get-accounts-account-id-targeting-criteria) to update them. -Use [GET accounts/:account\_id/line\_items](/x-ads-api/campaign-management#get-accounts-account-id-line-items) for a list of all line items and [GET  accounts/:account\_id/line\_items/:line\_item\_id](/x-ads-api/campaign-management#get-accounts-account-id-line-items-line-item-id) to retrieve a specific line item. +Use [GET accounts/:account\_id/line\_items](/x-ads-api/campaign-management/reference#get-accounts-account-id-line-items) for a list of all line items and [GET  accounts/:account\_id/line\_items/:line\_item\_id](/x-ads-api/campaign-management/reference#get-accounts-account-id-line-items-line-item-id) to retrieve a specific line item. #### Targeting options by placement [Promoted Tweets](https://business.x.com/help/what-are-promoted-tweets) and [Promoted Accounts](https://business.x.com/help/what-are-promoted-accounts) products can be made available on a variety of placements. [Promoted Trends (PTr)](https://business.x.com/help/what-are-promoted-trends) are not available via the API. -For possible placement combinations, refer to the [GET line_items/placements](/x-ads-api/campaign-management#get-line-items-placements) endpoint. Each placement has different options for targeting. Location, Platform and Gender are available for all. The other options are contextual to the type of placement. +For possible placement combinations, refer to the [GET line_items/placements](/x-ads-api/campaign-management/reference#get-line-items-placements) endpoint. Each placement has different options for targeting. Location, Platform and Gender are available for all. The other options are contextual to the type of placement. * **X Search**: Age Targeting, Devices, Events, Gender, Keyword Types (All), Language, Locations, Network Activation, Network Operators, Platform, Platform Version, Tailored Audiences, WiFi Only * **X Timeline**: Age Targeting, Devices, Events, Followers Of, Similar to Followers Of, Gender, Interest, Language, Locations, Network Activation, Network Operators, Non-exact Keyword Types, Partner Audience Types, Platform, Platform Version, Retargeting Types, Tailored Audiences, TV Targeting Types, WiFi Only @@ -463,29 +476,29 @@ For possible placement combinations, refer to the [GET line_items/placements](/x **Age Targeting**: Target users based on specific age buckets. A list of age bucket enums can be found on the [Enumerations](/x-ads-api/introduction) page. -[Events](https://business.x.com/help/event-targeting): Specify an event for targeting. Only one event can be used for targeting (per line item). Use the [GET targeting_criteria/events](/x-ads-api/campaign-management#get-targeting-criteria-events) endpoint to find events available for targeting. +[Events](https://business.x.com/help/event-targeting): Specify an event for targeting. Only one event can be used for targeting (per line item). Use the [GET targeting_criteria/events](/x-ads-api/campaign-management/reference#get-targeting-criteria-events) endpoint to find events available for targeting. [Gender](https://business.x.com/help/geo-gender-and-language-targeting): Target males (1) or females (2). Leave null to target all. -[Installed App Store Categories](https://business.x.com/help/installed-app-category-targeting): use this targeting type to target users based on the categories of apps they have installed or have indicated interest in. See [GET targeting\_criteria/app\_store_categories](/x-ads-api/campaign-management#get-targeting-criteria-app-store-categories). +[Installed App Store Categories](https://business.x.com/help/installed-app-category-targeting): use this targeting type to target users based on the categories of apps they have installed or have indicated interest in. See [GET targeting\_criteria/app\_store_categories](/x-ads-api/campaign-management/reference#get-targeting-criteria-app-store-categories). -[Interests](https://business.x.com/help/interest-and-username-targeting): Target users by interest. Get the interests list from [GET targeting_criteria/interests](/x-ads-api/campaign-management#get-targeting-criteria-interests). You can target up to 100 interests. +[Interests](https://business.x.com/help/interest-and-username-targeting): Target users by interest. Get the interests list from [GET targeting_criteria/interests](/x-ads-api/campaign-management/reference#get-targeting-criteria-interests). You can target up to 100 interests. -**Followers Of**: Target the followers of any fully promotable users for the current account (note, currently the primary account holder is the only fully-promotable user of that account). [GET accounts/:account\_id/promotable\_users](/x-ads-api/campaign-management#get-accounts-account-id-promotable-users) to get a list of promotable users. +**Followers Of**: Target the followers of any fully promotable users for the current account (note, currently the primary account holder is the only fully-promotable user of that account). [GET accounts/:account\_id/promotable\_users](/x-ads-api/campaign-management/reference#get-accounts-account-id-promotable-users) to get a list of promotable users. [Similar to Followers Of](https://business.x.com/help/interest-and-username-targeting): Target people with the same interests as followers of specific users. You can use up to 100 [Users](/x-api/fundamentals/data-dictionary#user). -[Locations](https://business.x.com/help/geo-gender-and-language-targeting): Specify up to 2,000 locations to target. Get list from [GET targeting_criteria/locations](/x-ads-api/campaign-management#get-targeting-criteria-locations). There are additional requirements for ads that target certain countries. See [Country Targeting and Display Requirements](/x-ads-api/campaign-management#country-targeting-and-display-requirements) for more information. +[Locations](https://business.x.com/help/geo-gender-and-language-targeting): Specify up to 2,000 locations to target. Get list from [GET targeting_criteria/locations](/x-ads-api/campaign-management/reference#get-targeting-criteria-locations). There are additional requirements for ads that target certain countries. See [Country Targeting and Display Requirements](/x-ads-api/campaign-management/reference#country-targeting-and-display-requirements) for more information. [Keywords](https://business.x.com/help/keyword-targeting): Keyword targeting options are specific by type of placement. You can use up to 1000 keywords for targeting (per line item). See the Keyword Types section for options. [Language Targeting](https://business.x.com/help/geo-gender-and-language-targeting): Target users who understand specific languages. -[Mobile Network Operator Targeting](https://business.x.com/help/device-carrier-and-new-mobile-user-targeting): Enables advertisers to target users based on mobile carrier, using the targeting type `NETWORK_OPERATOR` from [GET targeting\_criteria/network\_operators](/x-ads-api/campaign-management#get-targeting-criteria-network-operators). +[Mobile Network Operator Targeting](https://business.x.com/help/device-carrier-and-new-mobile-user-targeting): Enables advertisers to target users based on mobile carrier, using the targeting type `NETWORK_OPERATOR` from [GET targeting\_criteria/network\_operators](/x-ads-api/campaign-management/reference#get-targeting-criteria-network-operators). [New Mobile Device Targeting](https://business.x.com/help/device-carrier-and-new-mobile-user-targeting): Reach users based on the date that they first accessed X via their device, using the targeting type `NETWORK_ACTIVATION_DURATION` using operator_type of LT for less than and  `GTE` for greater than or equal. -[Platforms](/x-ads-api/campaign-management#get-targeting-criteria-platforms), [Platform Versions](/x-ads-api/campaign-management#get-targeting-criteria-platform-versions), [Devices](/x-ads-api/campaign-management#get-targeting-criteria-devices), and Wifi-Only: Allows targeting of mobile devices across a variety of vectors. Platforms is a high-level targeting type that can hit broad categories of phone. Example values are `iOS` and `Android`. Devices allow you to target users of specific mobile devices, for example the `iPhone 5s`, `Nexus 4`, or `Samsung Galaxy Note`. Platform versions allow you to target users of versions of specific mobile operating systems, down to the point release. Examples include iOS 7.1 and Android 4.4. Wifi-Only allows you to target only those users who are using their devices on a WiFi network; if this is not set, users using the carrier connection as well as WiFi will be targeted. +[Platforms](/x-ads-api/campaign-management/reference#get-targeting-criteria-platforms), [Platform Versions](/x-ads-api/campaign-management/reference#get-targeting-criteria-platform-versions), [Devices](/x-ads-api/campaign-management/reference#get-targeting-criteria-devices), and Wifi-Only: Allows targeting of mobile devices across a variety of vectors. Platforms is a high-level targeting type that can hit broad categories of phone. Example values are `iOS` and `Android`. Devices allow you to target users of specific mobile devices, for example the `iPhone 5s`, `Nexus 4`, or `Samsung Galaxy Note`. Platform versions allow you to target users of versions of specific mobile operating systems, down to the point release. Examples include iOS 7.1 and Android 4.4. Wifi-Only allows you to target only those users who are using their devices on a WiFi network; if this is not set, users using the carrier connection as well as WiFi will be targeted. * Users can target platforms and devices if there is no overlap. I can target Blackberry as a platform and iPad Air as a device simultaneously. * Users can target devices and os versions simultaneously. I can target iPad Air and iOS >= 7.0. @@ -496,7 +509,7 @@ For possible placement combinations, refer to the [GET line_items/placements](/x **[TV Targeting](https://support.x.com/articles/20170766-tv-targeting)** -**TV Show Targeting**: reach people that engage with specific TV programs. This targeting criteria can be configured to continuously target while a campaign is active with the `TV_SHOW` targeting type. Use the [GET targeting\_criteria/tv\_markets](/x-ads-api/campaign-management#get-targeting-criteria-tv-markets) and [GET targeting\_criteria/tv\_shows](/x-ads-api/campaign-management#get-targeting-criteria-tv-shows) endpoints to determine TV shows available. +**TV Show Targeting**: reach people that engage with specific TV programs. This targeting criteria can be configured to continuously target while a campaign is active with the `TV_SHOW` targeting type. Use the [GET targeting\_criteria/tv\_markets](/x-ads-api/campaign-management/reference#get-targeting-criteria-tv-markets) and [GET targeting\_criteria/tv\_shows](/x-ads-api/campaign-management/reference#get-targeting-criteria-tv-shows) endpoints to determine TV shows available. **Tweet Engager Retargeting** @@ -540,7 +553,7 @@ See our support document on [keyword targeting](https://business.x.com/en/help/c Emoji targeting is supported via keyword targeting. To use emoji targeting, simply create keyword targeting for Unicode codepoints representing that emoji such as _U+1F602_ (_xF0x9Fx98x82_ in UTF-8) for the ‘face with tears of joy’ emoji (😂). Emoji which we accept can be confirmed with the [twemoji](https://x.github.io/twemoji/preview.html) list. Targeting an emoji targets all variations. -For a summary of all values with required/optional and specific details for each, see [PUT accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria). +For a summary of all values with required/optional and specific details for each, see [PUT accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#get-accounts-account-id-targeting-criteria). #### Targeting Criteria Combinations @@ -595,11 +608,11 @@ By turning **off** standard delivery, we will serve impressions and generate e **Getting Started** -Standard delivery is the default option for all campaigns, so no action is required unless you wish to turn it off. To spend through your daily budget on a campaign as fast as possible set the `standard_delivery` parameter to `false` to set the pace to accelerated delivery (see [GET accounts/:account_id/campaigns](/x-ads-api/campaign-management#get-accounts-account-id-campaigns)). +Standard delivery is the default option for all campaigns, so no action is required unless you wish to turn it off. To spend through your daily budget on a campaign as fast as possible set the `standard_delivery` parameter to `false` to set the pace to accelerated delivery (see [GET accounts/:account_id/campaigns](/x-ads-api/campaign-management/reference#get-accounts-account-id-campaigns)). **Notes** -* “Day” is respective to X [advertiser account](/x-ads-api/campaign-management#accounts) timezone (eg. America/Los_Angeles). +* “Day” is respective to X [advertiser account](/x-ads-api/campaign-management/reference#accounts) timezone (eg. America/Los_Angeles). * Early results indicate that standard delivery will improve eCPE/CPF for advertisers, with more consistent coverage throughout the day. For more additional information about budgets and pacing please see the [Bidding and Auctions FAQ](https://business.x.com/en/help/troubleshooting/bidding-and-auctions-faqs.html). @@ -823,11 +836,11 @@ If the account link url is invoked with invalid parameters, the user will be sho #### Ongoing updates to the PMFI -Once the advertiser has been onboarded, the funding instrument can be managed using the [PUT accounts/:account_id/funding_instruments/:funding_instrument_id](/x-ads-api/campaign-management#get-accounts-account-id-funding-instruments) endpoint by only the partner who manages it. +Once the advertiser has been onboarded, the funding instrument can be managed using the [PUT accounts/:account_id/funding_instruments/:funding_instrument_id](/x-ads-api/campaign-management/reference#get-accounts-account-id-funding-instruments) endpoint by only the partner who manages it. ### Placements -There are several places where X ads can be displayed. This is set at the [line item](/x-ads-api/campaign-management#line-items) using the `placements` parameter. The possible values are: +There are several places where X ads can be displayed. This is set at the [line item](/x-ads-api/campaign-management/reference#line-items) using the `placements` parameter. The possible values are: * `ALL_ON_TWITTER` * `PUBLISHER_NETWORK` @@ -837,7 +850,7 @@ There are several places where X ads can be displayed. This is set at the [line * `SPOTLIGHT` * `TREND` -The line item’s `product_type` and `objective` determine which placements are allowed. The [GET line_items/placements](/x-ads-api/campaign-management#line-item-placements) endpoint can be used to retrieve the valid placement options for each product type. +The line item’s `product_type` and `objective` determine which placements are allowed. The [GET line_items/placements](/x-ads-api/campaign-management/reference#line-item-placements) endpoint can be used to retrieve the valid placement options for each product type. Additionally, the following table lists the valid placement and objective combinations. @@ -854,7 +867,7 @@ Additionally, the following table lists the valid placement and objective combin **Note**: It is not possible to specify _only_ `TWITTER_PROFILE` placement. -**Note**: `TWITTER_SEARCH` requires [keyword targeting](/x-ads-api/campaign-management#targeting-options). +**Note**: `TWITTER_SEARCH` requires [keyword targeting](/x-ads-api/campaign-management/reference#targeting-options). **Note**: The `REACH` objective must include `TWITTER_TIMELINE` placement. It can have either `ALL_ON_TWITTER`, any combination of placements that include `TWITTER_TIMELINE`, or `TWITTER_TIMELINE` on its own. @@ -869,7 +882,7 @@ Ad groups, known as line items in the Ads API, exist under campaigns and are use #### How do we create an Ad Group? -Ad Groups are created by calling [POST accounts/:account\_id/line\_items](/x-ads-api/campaign-management#post-accounts-account-id-line-items) multiple times for the same campaign ID, and keeping (possibly completely different) targeting and Tweets associated with those line items. There is a limit of 100 line items per campaign and a limit of 200 active campaigns for a single ads account. Across all campaigns, there is a limit of and 8,000 active line items per ads account. +Ad Groups are created by calling [POST accounts/:account\_id/line\_items](/x-ads-api/campaign-management/reference#post-accounts-account-id-line-items) multiple times for the same campaign ID, and keeping (possibly completely different) targeting and Tweets associated with those line items. There is a limit of 100 line items per campaign and a limit of 200 active campaigns for a single ads account. Across all campaigns, there is a limit of and 8,000 active line items per ads account. #### Why should we add support for Ad Groups? @@ -905,15 +918,15 @@ The following guide outlines the steps required to set up a PREROLL_VIEWS campai * [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) (for video upload) * [POST accounts/:account\_id/media\_library](/x-ads-api/creatives#media-library) (for video association to ads account) -* [POST accounts/:account_id/campaigns](/x-ads-api/campaign-management#post-accounts-account-id-campaigns) (create campaign) -* [GET content_categories](/x-ads-api/campaign-management#content-categories) (to get the mapping of content categories to IAB categories) -* [GET accounts/:account\_id/curated\_categories](/x-ads-api/campaign-management#curated-categories-2) -* [GET publishers](/x-ads-api/campaign-management#publishers) -* [POST accounts/:account\_id/line\_item\_curated\_categories](/x-ads-api/campaign-management#line-item-curated-categories) -* [POST accounts/:account\_id/line\_items](/x-ads-api/campaign-management#campaigns) (create ad group) -* [POST accounts/:account\_id/media\_creatives](/x-ads-api/campaign-management#post-accounts-account-id-media-creatives) (to associate video with ad group) +* [POST accounts/:account_id/campaigns](/x-ads-api/campaign-management/reference#post-accounts-account-id-campaigns) (create campaign) +* [GET content_categories](/x-ads-api/campaign-management/reference#content-categories) (to get the mapping of content categories to IAB categories) +* [GET accounts/:account\_id/curated\_categories](/x-ads-api/campaign-management/reference#curated-categories-2) +* [GET publishers](/x-ads-api/campaign-management/reference#publishers) +* [POST accounts/:account\_id/line\_item\_curated\_categories](/x-ads-api/campaign-management/reference#line-item-curated-categories) +* [POST accounts/:account\_id/line\_items](/x-ads-api/campaign-management/reference#campaigns) (create ad group) +* [POST accounts/:account\_id/media\_creatives](/x-ads-api/campaign-management/reference#post-accounts-account-id-media-creatives) (to associate video with ad group) * [POST accounts/:account\_id/preroll\_call\_to\_action](/x-ads-api/creatives#preroll-call-to-actions) (set CTA and redirect URL) -* [POST batch/accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#post-batch-accounts-account-id-targeting-criteria) (targeting) +* [POST batch/accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#post-batch-accounts-account-id-targeting-criteria) (targeting) #### Steps @@ -959,7 +972,7 @@ POST https://ads-api.x.com/8/55w3kv/media\_library?media\_key=3_9312367385545195 ### Campaign Creation -Create the [campaign](/x-ads-api/campaign-management#post-accounts-account-id-campaigns) and [line item/ad group](/x-ads-api/campaign-management#campaigns). Line items should be created with an `objective` of `VIDEO_VIEWS_PREROLL`, and a `product_type` of `MEDIA`. The `categories` parameter must also be set to the appropriate [advertiser business categories](/x-ads-api/campaign-management#advertiser-business-categories). +Create the [campaign](/x-ads-api/campaign-management/reference#post-accounts-account-id-campaigns) and [line item/ad group](/x-ads-api/campaign-management/reference#campaigns). Line items should be created with an `objective` of `VIDEO_VIEWS_PREROLL`, and a `product_type` of `MEDIA`. The `categories` parameter must also be set to the appropriate [advertiser business categories](/x-ads-api/campaign-management/reference#advertiser-business-categories). ```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 @@ -1003,7 +1016,7 @@ POST https://ads-api.x.com/8/accounts/55w3kv/campaigns?name=test-curated-categor ``` ### Line Item Creation -Line items must have the categories parameter set to the appropriate set of IAB categories, retrieved via the [GET content_categories](/x-ads-api/campaign-management#content-categories) endpoint. These content categories each correspond to one or more IAB categories. +Line items must have the categories parameter set to the appropriate set of IAB categories, retrieved via the [GET content_categories](/x-ads-api/campaign-management/reference#content-categories) endpoint. These content categories each correspond to one or more IAB categories. In order to use these values, partners must select an appropriate content category and use the entire set of iab_categories returned in the response, to set the categories parameter on the line items endpoint. Any partial application of the iab_categories will result in the entire group being set on the line item. For example, ```json @@ -1319,14 +1332,14 @@ An advertiser may choose to target either a Content Category or a Curated Catego ### Curated Categories -Curated Categories allow advertisers to target a preset group of publishers and can be retrieved using the  [GET curated_categories](/x-ads-api/campaign-management#curated-categories-2) endpoint. These categories are country specific, and therefore require that the line item target the appropriate country based on the country_code of the category. +Curated Categories allow advertisers to target a preset group of publishers and can be retrieved using the  [GET curated_categories](/x-ads-api/campaign-management/reference#curated-categories-2) endpoint. These categories are country specific, and therefore require that the line item target the appropriate country based on the country_code of the category. In order to use one of these categories, the following steps are required in the specific order listed: 1. The line item needs to target the appropriate country based on the country_code of the Curated Category -2. The [POST line\_item\_curated_categories](/x-ads-api/campaign-management#line-item-curated-categories) endpoint must be used to associate the line item with a specific curated\_category\_id.  +2. The [POST line\_item\_curated_categories](/x-ads-api/campaign-management/reference#line-item-curated-categories) endpoint must be used to associate the line item with a specific curated\_category\_id.  -**Note:** Associating a line item with a curated category will also limit the number of publishers that can be denylisted to 5. The full list of user_id used to denylist specific publishers can be retrieved from the [GET publishers](/x-ads-api/campaign-management#publishers) endpoint. Additionally, a given line item may target no more than one Curated Category at a time. +**Note:** Associating a line item with a curated category will also limit the number of publishers that can be denylisted to 5. The full list of user_id used to denylist specific publishers can be retrieved from the [GET publishers](/x-ads-api/campaign-management/reference#publishers) endpoint. Additionally, a given line item may target no more than one Curated Category at a time. The following example illustrates how to associate a curated category id: b0xt which is only available in the US, with the line item created in the previous step. @@ -1422,10 +1435,10 @@ POST https://ads-api.x.com/8/accounts/55w3kv/line\_item\_curated\_categories?lin ### Content Categories -Content categories, also referred to as Standard Categories can be retrieved from the [GET curated_categories](/x-ads-api/campaign-management#get-accounts-account-id-curated-categories) endpoint. These categories can then be targeted by the line item using the batch targeting criteria endpoints. The following example illustrates how to select a particular content category, id: sr which maps to “News & Current Events” and apply it to the line item. +Content categories, also referred to as Standard Categories can be retrieved from the [GET curated_categories](/x-ads-api/campaign-management/reference#get-accounts-account-id-curated-categories) endpoint. These categories can then be targeted by the line item using the batch targeting criteria endpoints. The following example illustrates how to select a particular content category, id: sr which maps to “News & Current Events” and apply it to the line item. -**Note**: The entire set of iab_categories in the [GET curated_categories](/x-ads-api/campaign-management#get-accounts-account-id-curated-categories) response must be targeted via the targeting criteria endpoint. Failing to do so will result in a validation error.  +**Note**: The entire set of iab_categories in the [GET curated_categories](/x-ads-api/campaign-management/reference#get-accounts-account-id-curated-categories) response must be targeted via the targeting criteria endpoint. Failing to do so will result in a validation error.  ```json @@ -1524,7 +1537,7 @@ POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria ##### Associate the account media (video) with the line item -Use the [POST accounts/:account\_id/media\_creatives](/x-ads-api/campaign-management#post-accounts-account-id-media-creatives) endpoint to associate the video with an ad group. +Use the [POST accounts/:account\_id/media\_creatives](/x-ads-api/campaign-management/reference#post-accounts-account-id-media-creatives) endpoint to associate the video with an ad group. ```json POST https://ads-api.x.com/8/accounts/55w3kv/media_creatives line\_item\_id=4bii5&account\_media\_id=knb @@ -1579,11 +1592,11 @@ line\_item\_id=4bii5&call\_to\_action=VISIT\_SITE&call\_to\_action\_url=https%3A #### Set targeting criteria -The targetting criterion utilized for pre-roll video ads is only avaialble using our batch targeting criteria endpoint [POST batch/accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#post-batch-accounts-account-id-targeting-criteria). +The targetting criterion utilized for pre-roll video ads is only avaialble using our batch targeting criteria endpoint [POST batch/accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#post-batch-accounts-account-id-targeting-criteria). Use `CONTENT_PUBLISHER_USER` as negated targeting to exclude the ad from being paired with a set of users. Provide the X `user_id`  or publisher\_user\_id for the handles to exclude. -The [GET publishers](/x-ads-api/campaign-management#publishers) endpoint can be used to retrieve the list of user_id to exclude for Content Categories. The publisher\_user\_id returned in the [GET curated_categories](/x-ads-api/campaign-management#curated-categories-2) response can be used to retrieve a similar exclusion list for Curated Categories. +The [GET publishers](/x-ads-api/campaign-management/reference#publishers) endpoint can be used to retrieve the list of user_id to exclude for Content Categories. The publisher\_user\_id returned in the [GET curated_categories](/x-ads-api/campaign-management/reference#curated-categories-2) response can be used to retrieve a similar exclusion list for Curated Categories. **Note:** A maximum of 5 publisher\_user\_id can be excluded for Curated Categories and 50 user_id for Content Categories. ```json @@ -1634,7 +1647,7 @@ POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria ``` #### Launch campaign -When you’re ready to launch your campaign, simply un-pause using [PUT accounts/:account_id/campaigns/:id](/x-ads-api/campaign-management#put-accounts-account-id-line-items-line-item-id). +When you’re ready to launch your campaign, simply un-pause using [PUT accounts/:account_id/campaigns/:id](/x-ads-api/campaign-management/reference#put-accounts-account-id-line-items-line-item-id). PUT https://ads-api.x.com/8/accounts/55w3kv/campaigns/f2rp3? entity_status=ACTIVE @@ -1687,6310 +1700,10 @@ TL;DR: from an API standpoint, this change is quite simple: you can now target k * Create the targeting criteria for this newly created line item with either `BROAD_KEYWORD` and set your keyword value(s). [POST accounts/:account\_id/targeting\_criteria](https://dev.x.com/ads/reference/post/accounts/%3Aaccount_id/targeting_criteria) * You can update the keywords with [PUT accounts/:account\_id/targeting\_criteria](https://dev.x.com/ads/reference/put/accounts/%3Aaccount_id/targeting_criteria) * Once your campaign is running, get the stats on your line item to gauge performance. [GET stats/accounts/:account_id](https://dev.x.com/ads/reference/get/stats/accounts/%3Aaccount_id) -## API Reference - -### Accounts - - -#### GET accounts[](#get-accounts "Permalink to this headline") - -Retrieve details for some or all advertising-enabled accounts the authenticating user has access to. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| account_ids
_optional_ | Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| q
_optional_ | An optional query to scope resource by `name`.

**Note**: This performs case-insensitive prefix matching.

Type: string

Min, Max length: `1`, `255` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/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 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[](#example-request "Permalink to this headline") - -```json -GET https://ads-api.x.com/12/accounts?account_ids=18ce54d4x5t -``` - -**Example Response[](#example-response "Permalink to this headline")** -```json - { - "request": { - "params": { - "account_ids": [ - "18ce54d4x5t" - ] - } - }, - "next_cursor": null, - "data": [ - { - "name": "API McTestface", - "business_name": null, - "timezone": "America/Los_Angeles", - "timezone_switch_at": "2016-07-21T07:00:00Z", - "id": "18ce54d4x5t", - "created_at": "2016-07-21T22:42:09Z", - "updated_at": "2017-07-06T16:51:04Z", - "business_id": null, - "approval_status": "ACCEPTED", - "deleted": false - } - ] - } -``` -#### GET accounts/:account_id[](#get-accounts-account-id "Permalink to this headline") - -Retrieve a specific account that the authenticating user has access to. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t` - -**Example Response[](#example-response "Permalink to this headline")** -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t" - } - }, - "data": { - "name": "API McTestface", - "business_name": null, - "timezone": "America/Los_Angeles", - "timezone_switch_at": "2016-07-21T07:00:00Z", - "id": "18ce54d4x5t", - "created_at": "2016-07-21T22:42:09Z", - "updated_at": "2017-07-06T16:51:04Z", - "industry_type": "TRAVEL", - "business_id": null, - "approval_status": "ACCEPTED", - "deleted": false - } - } -``` -#### POST accounts[](#post-accounts "Permalink to this headline") - - -Note: **SANDBOX ONLY** - -Create an ads account in the sandbox environment. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api-sandbox.x.com/12/accounts` - -**Parameters[](#parameters "Permalink to this headline")** - -None - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api-sandbox.x.com/12/accounts` - -**Example Response[](#example-response "Permalink to this headline")** -```json - { - "request": { - "params": {} - }, - "next_cursor": null, - "data": [ - { - "name": "Sandbox account", - "business_name": null, - "timezone": "America/Los_Angeles", - "timezone_switch_at": null, - "id": "gq12fh", - "created_at": "2016-07-18T23:02:20Z", - "updated_at": "2016-07-18T23:02:20Z", - "business_id": null, - "approval_status": "ACCEPTED", - "deleted": false - } - ] - } -``` -#### PUT accounts/:account_id[](#put-accounts-account-id "Permalink to this headline") - - -Updates the account name and/or industry type. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#accounts).
The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| name
_optional_ | The name of account.

Type: string

Example: `API McTestface` | -| industry_type
_optional_ | Industry that the account is associated with.

Type: string

Possible values: `AGENCY`, `BUSINESS_TO_BUSINESS`, `ONLINE_SERVICES`, `EDUCATION`, `FINANCIAL`, `HEALTH`, `GOVERNMENT`, `MEDIA`, `MOBILE`, `RESTAURANT`, `RETAIL`, `TECHNOLOGY`, `TRAVEL`, `OTHER` | - -**Example Request[](#example-request "Permalink to this headline")** - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY` - -**Example Response[](#example-response "Permalink to this headline")** -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t" - "name"": "API McTestface 2", - "industry_type": "TECHNOLOGY" - } - }, - "data": { - "name": "API McTestface 2", - "business_name": null, - "timezone": "America/Los_Angeles", - "timezone_switch_at": "2016-07-21T07:00:00Z", - "id": "18ce54d4x5t", - "created_at": "2016-07-21T22:42:09Z", - "updated_at": "2017-07-06T16:51:04Z", - "industry_type": "TECHNOLOGY", - "business_id": null, - "approval_status": "ACCEPTED", - "deleted": false - } - } -``` -#### DELETE accounts/:account_id[](#delete-accounts-account-id "Permalink to this headline") - - -Note: **SANDBOX ONLY** - -Delete an ads account in the sandbox environment. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api-sandbox.x.com/12/accounts/:account_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#accounts).

The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh` - -**Example Response[](#example-response "Permalink to this headline")** -```json - { - "data": { - "name": "Sandbox account", - "timezone": "America/Los_Angeles", - "timezone_switch_at": null, - "id": "gq12fh", - "created_at": "2016-07-18T23:02:20Z", - "updated_at": "2017-08-23T18:21:10Z", - "approval_status": "ACCEPTED", - "deleted": true - }, - "request": { - "params": { - "account_id": "gq12fh" - } - } - } -``` -### Account Apps - -[Run in Postman ❯](https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87) - -#### GET account_apps[](#get-account-apps "Permalink to this headline") - - -Retrieve details for all mobile apps that are associated with the specified ad account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/account_apps` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps` - -**Example Response[](#example-response "Permalink to this headline")** -```json - { - "request": { - "params": { - "account_ids": [ - "18ce54d4x5t" - ] - } - }, - "next_cursor": null, - "data": [ - { - "app_store_identifier": "com.twitter.android", - "conversion_tracking_enabled": false, - "deep_link_pattern": "twitter://", - "id": "4x", - "created_at": "2019-06-20T22:36:16Z", - "updated_at": "2021-10-19T20:05:29Z", - "os_type": "Android", - "deleted": false - } - ] - } -``` -### Account History - - - -#### GET accounts/:account\_id/account\_history[](#get-accounts-account-id-account-history "Permalink to this headline") - - -Retrieve a summary of changes made to the `entity_id` specified in the request. - -**Note**: This endpoint is currently in beta and requires allowlisting. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/account_history` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| account_id
_required_ | The identifier for the leveraged account.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| entity_type
_required_ | The entity type to retrieve data for.

Type: enum

Example: `PROMOTED_TWEET`
Possible values: `CAMPAIGN`, `LINE_ITEM`, `PROMOTED_TWEET`, `TARGETING_CRITERIA`, `PROMOTED_ACCOUNT` | -| entity_id
_required_ | The specific entitiy to retrieve data for.

Type: string

Example: `8u94t` | -| start_time
_required_ | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-19T07:00:00Z` | -| end_time
_required_ | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-26T07:00:00Z` | -| user_id
_optional_ | Scopes the response to a specific user.

Type: long

Example: `3271358660` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1` - -**Example Response[](#example-response "Permalink to this headline")** - -```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" - } - ] - } -``` -### Advertiser Business Categories - - -#### GET advertiser\_business\_categories[](#get-advertiser-business-categories "Permalink to this headline") - -Request the valid advertiser business `categories` for Ad Groups (`line_items`) to describe an advertiser's brand to publishers. - -Note: These categories apply only to `line_items` with the `PREROLL_VIEWS` objective and are separate from the `content_categories` used for targeting criteria. - -Each `advertiser_business_categories` represents a collection of [IAB Categories](/x-ads-api/campaign-management#iab-categories). When creating an Ad Group with the `PREROLL_VIEWS` objective, one or two `advertiser_business_categories` must be set for the Ad Group. This can be done by setting the value of the `categories` request parameter on the [line item](/x-ads-api/campaign-management#line-items) endpoint to the set of corresponding `iab_categories` available through this endpoint. - -Additional details can be found in the [Video Views Preroll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective) - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/advertiser_business_categories` - -**Parameters[](#parameters "Permalink to this headline")** - -No request parameters - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/advertiser_business_categories` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "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" - ] - } - ] - } -``` -### Audience Estimate - - -POST accounts/:account\_id/audience\_estimate[](#post-accounts-account-id-audience-estimate "Permalink to this headline") - -#### Determine the approximate audience size of your campaigns. - -This endpoint accepts an array of JSON objects containing the parameters for the targeting criteria objects. A list of required and optional targeting criteria parameters are available on the [POST accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#post-accounts-account-id-targeting-criteria) endpoint. Requests must be HTTP POST with a JSON content body with a `Content-Type: application/json` header. - -**Note**: It is required that you specify at least one **primary** targeting criterion; you can see a list of all primary targeting criteria in our [campaigns targeting page](/x-ads-api/campaign-management#targeting). - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/audience_estimate` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| targeting_criteria
_required_ | A JSON object containing all the parameters for the targeting criteria objects. A list of required and optional targeting criteria parameters are available on the [POST accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#post-accounts-account-id-targeting-criteria) endpoint. | -| operator_type
_optional_ | Specify the relationship that the targeting criterion should have. For example, to set negated targeting, use `operator_type=NE`.

Type: enum

Possible values: `EQ`, `NE`

Default: `EQ` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate` - -```json - { - "targeting_criteria": [ - { - "targeting_type": "BROAD_KEYWORD", - "targeting_value": "nba", - "operator_type": "EQ" - }, - { - "targeting_type": "BROAD_KEYWORD", - "targeting_value": "tech", - "operator_type": "NE" - }, - { - "targeting_type": "LOCATION", - "targeting_value": "96683cc9126741d1", - "operator_type": "EQ" - }, - { - "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER", - "targeting_value": "14230524" - }, - { - "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER", - "targeting_value": "90420314" - } - ] - } -``` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "targeting_criteria": null, - "account_id": "18ce54d4x5t" - } - }, - "data": { - "audience_size": { - "min": 38236294, - "max": 42261167 - } - } - } -``` -### Authenticated User Access - - -#### GET accounts/:account\_id/authenticated\_user_access[](#get-accounts-account-id-authenticated-user-access "Permalink to this headline") - -Retrieve the permissions of the currently authenticated user (access_token) as they relate to the specified ads account. These permissions match those exposed on ads.x.com. - -Possible values include: - -* `ACCOUNT_ADMIN`: Full access to modify campaigns and view stats, including the ability to add or remove users and change settings -* `AD_MANAGER`: Full access to modify campaigns and view stats, but cannot add or remove users or change settings -* `CREATIVE_MANAGER`: Access to modify creatives and view previews, but no access to create or modify campaigns -* `CAMPAIGN_ANALYST`: Access to view campaigns and view stats, but no access to create or modify campaigns -* `ANALYST` ("Organic Analyst" on ads.x.com): Access to view organic analytics and audience insights, but no access to create, modify, or view campaigns -* `PARTNER_AUDIENCE_MANAGER`: API-only access to view and modify data partner audiences, but no access to campaigns, creatives, or other audience types. - -In addition, the `TWEET_COMPOSER` permission indicates that the authenticated user can create nullcasted (or "Promoted-only") Tweets on behalf of the advertiser. This is only available for users with `ACCOUNT_ADMIN`, `AD_MANAGER`, or `CREATIVE_MANAGER` access. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/authenticated_user_access` - -**Parameters[](#parameters "Permalink to this headline")** - -None - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/authenticated_user_access` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "user_id": "2417045708", - "permissions": [ - "ACCOUNT_ADMIN", - "TWEET_COMPOSER" - ] - }, - "request": { - "params": { - "account_id": "18ce54d4x5t" - } - } - } -``` - -### Bidding Rules - - -#### GET bidding_rules[](#get-bidding-rules "Permalink to this headline") - -Retrieve the bidding rules for some or all currencies. The response will indicate the minimum and maximum CPE (cost-per-engagement) bids. - -While these bidding rules change rarely, it is suggested that your systems refresh from these endpoints at least monthly. - -**Resource URL[](#resource-url "Permalink to this headline")** -`https://ads-api.x.com/12/bidding_rules` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| currency
_optional_ | The type of a currency to filter results by, identified using [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217). This is a three-letter string "USD" or "EUR". Omit this parameter to retrieve all bidding rules. associated with the authenticating user.

Type: string

Example: `USD` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/bidding_rules?currency=USD` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "currency": "USD" - } - }, - "data_type": "bidding_rule", - "data": [ - { - "currency": "USD", - "minimum_cpe_bid_local_micro": 10000, - "maximum_cpe_bid_local_micro": 1000000000, - "minimum_denomination": 10000 - } - ], - "total_count": 1 - } -``` -### Campaigns - - -#### GET accounts/:account_id/campaigns[](#get-accounts-account-id-campaigns "Permalink to this headline") - -Retrieve details for some or all campaigns associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/campaigns` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "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[](#get-accounts-account-id-campaigns-campaign-id "Permalink to this headline") - -Retrieve a specific campaign associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "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[](#post-accounts-account-id-campaigns "Permalink to this headline") - -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 X Account Manager. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/campaigns` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** +## Full API Reference -`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` +For the complete list of endpoints with request/response examples and attribute tables, see the **[Campaign Management API Reference](/x-ads-api/campaign-management/reference)** page. -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "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[](#post-batch-accounts-account-id-campaigns "Permalink to this headline") - -Allows the batch creation of new [campaigns](#post-accounts-account-id-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[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/batch/accounts/:account_id/campaigns` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](#post-accounts-account-id-campaigns). | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns` - -```json - [ - { - "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[](#example-response "Permalink to this headline")** - -```json - { - "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[](#put-accounts-account-id-campaigns-campaign-id "Permalink to this headline") - -Update the specified campaign associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "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-accounts-account-id-campaigns-campaign-id "Permalink to this headline") - -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[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "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 - } - } -``` -### Content Categories - - -#### GET content_categories[](#get-content-categories "Permalink to this headline") - -Request the valid content `categories` to be set as `targeting_criteria` for a line item. - -Each `content_category` maps to one or more [IAB Categories](/x-ads-api/campaign-management#iab-categories). This can be done by setting the `targeting_type` to `IAB_CATEGORY` on the batch `targeting_critera` endpoint to include the set of corresponding `iab_categories` returned by the `content_categories` request. Failure to do so will result in a validation error. - -Publisher details for each of these content categories can be retrieved using the [GET publishers](/x-ads-api/campaign-management#publishers) endpoint. - -Additional details can be found in the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective). - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/content_categories` - -**Parameters[](#parameters "Permalink to this headline")** - -No request parameters - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/content_categories` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": {} - }, - "next_cursor": null, - "data": [ - { - "name": "Automotive (Cars, Trucks, Racing)", - "id": "ru", - "iab_categories": [ - "IAB2" - ], - "publishers_in_last_thirty_days": 12, - "videos_monetized_in_last_thirty_days": 316 - }, - { - "name": "Comedy", - "id": "sk", - "iab_categories": [ - "IAB1-4" - ], - "publishers_in_last_thirty_days": 19, - "videos_monetized_in_last_thirty_days": 174 - }, - { - "name": "Digital Creators", - "id": "sl", - "iab_categories": [ - "IAB25-1" - ], - "publishers_in_last_thirty_days": 110, - "videos_monetized_in_last_thirty_days": 1257 - }, - { - "name": "Entertainment & Pop Culture", - "id": "sm", - "iab_categories": [ - "IAB1-1", - "IAB1-2", - "IAB1-3", - "IAB1-5" - ], - "publishers_in_last_thirty_days": 120, - "videos_monetized_in_last_thirty_days": 3482 - }, - { - "name": "Financial & Business News", - "id": "sn", - "iab_categories": [ - "IAB3", - "IAB13", - "IAB21" - ], - "publishers_in_last_thirty_days": 29, - "videos_monetized_in_last_thirty_days": 1461 - }, - { - "name": "Food & Drink", - "id": "so", - "iab_categories": [ - "IAB8-8", - "IAB8-12", - "IAB8-17", - "IAB8-2", - "IAB8-3", - "IAB8-7", - "IAB8-11", - "IAB8-4", - "IAB8-14", - "IAB8-10", - "IAB8-15", - "IAB8-13", - "IAB8-9", - "IAB8-16", - "IAB8-6", - "IAB8-1" - ], - "publishers_in_last_thirty_days": 24, - "videos_monetized_in_last_thirty_days": 516 - }, - { - "name": "Lifestyle (Fashion, Travel, Wellness)", - "id": "sp", - "iab_categories": [ - "IAB16", - "IAB9-21", - "IAB9-4", - "IAB9-25", - "IAB9-8", - "IAB4", - "IAB9-3", - "IAB9-15", - "IAB7", - "IAB6", - "IAB9-11", - "IAB9-16", - "IAB9-7", - "IAB9-20", - "IAB9-24", - "IAB9-17", - "IAB9-12", - "IAB9-31", - "IAB9-27", - "IAB10", - "IAB9-10", - "IAB9-23", - "IAB9-6", - "IAB9-18", - "IAB9-13", - "IAB9-1", - "IAB9-28", - "IAB20", - "IAB9-5", - "IAB9-26", - "IAB22", - "IAB23", - "IAB9-9", - "IAB9-22", - "IAB18", - "IAB9-2", - "IAB9-19", - "IAB9-14", - "IAB9-29" - ], - "publishers_in_last_thirty_days": 67, - "videos_monetized_in_last_thirty_days": 2412 - }, - { - "name": "Music", - "id": "sq", - "iab_categories": [ - "IAB1-6" - ], - "publishers_in_last_thirty_days": 31, - "videos_monetized_in_last_thirty_days": 518 - }, - { - "name": "News & Current Events", - "id": "sr", - "iab_categories": [ - "IAB12", - "IAB14" - ], - "publishers_in_last_thirty_days": 125, - "videos_monetized_in_last_thirty_days": 5507 - }, - { - "name": "Politics", - "id": "s4", - "iab_categories": [ - "IAB11" - ], - "publishers_in_last_thirty_days": 19, - "videos_monetized_in_last_thirty_days": 1402 - }, - { - "name": "Science & Education", - "id": "ss", - "iab_categories": [ - "IAB5", - "IAB15" - ], - "publishers_in_last_thirty_days": 7, - "videos_monetized_in_last_thirty_days": 132 - }, - { - "name": "Sports", - "id": "se", - "iab_categories": [ - "IAB17" - ], - "publishers_in_last_thirty_days": 403, - "videos_monetized_in_last_thirty_days": 18281 - }, - { - "name": "Technology", - "id": "sg", - "iab_categories": [ - "IAB19" - ], - "publishers_in_last_thirty_days": 13, - "videos_monetized_in_last_thirty_days": 1089 - }, - { - "name": "Television", - "id": "sh", - "iab_categories": [ - "IAB1-7" - ], - "publishers_in_last_thirty_days": 58, - "videos_monetized_in_last_thirty_days": 1307 - }, - { - "name": "Esports & Video Games", - "id": "s0", - "iab_categories": [ - "IAB9-30" - ], - "publishers_in_last_thirty_days": 109, - "videos_monetized_in_last_thirty_days": 1844 - } - ], - "total_count": 15 - } -``` -### Curated Categories - - -#### GET accounts/:account\_id/curated\_categories[](#get-accounts-account-id-curated-categories "Permalink to this headline") - -Retrieve a list of available Curated Categories for the given `country_codes` - -Each `curated_category` is only available in specific countries specified by the `country_codes` in the response. - -Additional details can be found in the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective). - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/curated_categories` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| country_codes
_required_ | Scope the response to just the desired countries by specifying a comma-separated list of two letter ISO country codes. Up to 200 IDs may be provided.

Type: string

Example: `US` | -| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "country_codes": [ - "US" - ], - "account_id": "18ce54d4x5t" - } - }, - "next_cursor": null, - "data": [ - { - "name": "Basketball", - "description": "Run next to the best of everyday basketball content including college teams, professional teams, and the top sports media handles sharing on and off-season basketball video.", - "country_codes": [ - "US" - ], - "publisher_user_ids": [ - "20265254", - "378174762", - "900368808", - "18939563", - "18371803", - "18360370", - "770658432928079872", - "11026952", - "37085464", - "16212685", - "57422635", - "281669945", - "7117962", - "23065057", - "41688179", - "29779226", - "900280416", - "364460082", - "902030382", - "19409270", - "19077044", - "18139461", - "14992591", - "66753565", - "667563", - "16727749", - "40941404", - "18481113", - "791598918", - "16201775", - "15900167", - "45891626", - "191894553", - "2181233851", - "34352904", - "171483987", - "454122399", - "57415242", - "19263978", - "902089998", - "423540866", - "2715223320", - "22185437", - "17292143", - "55590247", - "66757066", - "22642626", - "41604618", - "87275465", - "22643259", - "32414973", - "73406718", - "20346956", - "413422891", - "45412765", - "19537303", - "459511725", - "30954864", - "21308488", - "18552281", - "19924520", - "24903350", - "851142163", - "26270913", - "20444254", - "26074296", - "6395222", - "15537451", - "28672101", - "38053254", - "24925573", - "19564719", - "18164425", - "22815383", - "20196159" - ], - "id": "929wbl6ymlfk", - "created_at": "2019-11-08T21:12:47Z", - "updated_at": "2021-03-09T20:36:44Z", - "videos_monetized_in_last_thirty_days": 2446 - }, - { - "name": "Gaming Personalities", - "description": "Run next to the best of everyday gaming content exclusively from a list of some of online gaming’s biggest and most loved digital creators.", - "country_codes": [ - "US" - ], - "publisher_user_ids": [ - "90779436", - "268270621", - "567167802", - "246596682", - "474919140", - "284422688", - "185909682", - "4767225325", - "2559865245", - "186888760", - "161418822", - "141021153", - "352881953", - "1117931702", - "146556805", - "357294577", - "234526497", - "266687361", - "214201922", - "9451052", - "2163885564", - "2231422037", - "116952434", - "399909209", - "15993650", - "974356091193741312", - "210839744", - "2313002094", - "159916388", - "3258981481", - "231992478", - "182236262", - "386884916", - "22705686", - "4140881832", - "995979576", - "2244953047", - "311775629", - "98821255", - "2733210014", - "2741078150" - ], - "id": "94ngssfrr01x", - "created_at": "2019-12-02T20:45:12Z", - "updated_at": "2021-03-09T20:18:13Z", - "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", - "25084916", - "764347046", - "19853312", - "348590880" - ], - "id": "8tujg1lvi8sn", - "created_at": "2019-08-15T20:48:51Z", - "updated_at": "2021-03-09T20:34:13Z", - "videos_monetized_in_last_thirty_days": 254 - }, - { - "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 - }, - { - "name": "Soccer", - "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.", - "country_codes": [ - "US" - ], - "publisher_user_ids": [ - "21677316", - "20636347", - "4704552148", - "14573900", - "22556296", - "1415791555", - "107146095", - "17288520", - "213474069", - "17493398", - "44990136", - "452155423", - "17744542", - "16303450", - "2841146601", - "2413176055", - "29739264", - "38580532", - "953476292913106945", - "27092557", - "86356439", - "34613288", - "3170659367", - "119593082", - "73412535", - "627586654", - "15891449", - "23011345", - "96951800", - "15997022", - "16960789", - "21919642", - "102965285", - "17224076", - "36432200", - "1410055968" - ], - "id": "9ddrgesiap6o", - "created_at": "2020-02-28T22:43:26Z", - "updated_at": "2021-01-26T17:54:55Z", - "videos_monetized_in_last_thirty_days": 421 - } - ], - "total_count": 9 - } -``` - -#### GET accounts/:account\_id/curated\_categories/:curated\_category\_id[](#get-accounts-account-id-curated-categories-curated-category-id "Permalink to this headline") - -Retrieve details for a specific `curated_category_id` - -Each `curated_category` is only available in specific countries specified by the `country_codes` in the response. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/curated_categories/:curated_category_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| curated\_category\_id
_required_ | A reference to the Curated Category you are operating with in the request.

Type: string

Example: `9ddrgesiap6o` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "id": "9ddrgesiap6o", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "name": "Soccer", - "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.", - "country_codes": [], - "publisher_user_ids": [ - "21677316", - "20636347", - "4704552148", - "14573900", - "22556296", - "1415791555", - "107146095", - "17288520", - "213474069", - "17493398", - "44990136", - "452155423", - "17744542", - "16303450", - "2841146601", - "2413176055", - "29739264", - "38580532", - "953476292913106945", - "27092557", - "86356439", - "34613288", - "3170659367", - "119593082", - "73412535", - "627586654", - "15891449", - "23011345", - "96951800", - "15997022", - "16960789", - "21919642", - "102965285", - "17224076", - "36432200", - "1410055968" - ], - "id": "9ddrgesiap6o", - "created_at": "2020-02-28T22:43:26Z", - "updated_at": "2021-01-26T17:54:55Z", - "videos_monetized_in_last_thirty_days": 421 - } - } -``` -### Features - - -#### GET accounts/:account_id/features[](#get-accounts-account-id-features "Permalink to this headline") - -Retrieve the collection of granted features accessible by this ads account. Features are indicated by a descriptive feature key and are only exposed on this endpoint if they are introduced in beta or an otherwise limited release and are available in the Ads API. Features that do not meet this criteria will not be exposed on this endpoint. - -**Note**: This endpoint serves to aid Ads API ecosystem development by improving visibility into client access to beta releases. API developers can not request access to features on behalf of an advertiser. These requests can only be made by the advertiser to their X account manager. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/features` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| feature_keys
_optional_ | An optional parameter that enables querying for a specific feature key. Requests may include multiple comma-separated keys.

**Note**: Only the features that are accessible by this account will be included in the response.

Type: enum

Possible values: `REACH_AND_FREQUENCY_ANALYTICS`, `REACH_FREQUENCY_CAP`, `WEBSITE_CLICKS_CPM_BILLING` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t" - } - }, - "data": [ - "CITY_TARGETING", - "CONVERSATION_CARD", - "PROMOTED_MEDIA_POLLS", - "REACH_AND_FREQUENCY_ANALYTICS", - "REACH_FREQUENCY_CAP", - "UNIVERSAL_LOOKALIKE" - ] - } -``` - -#### POST accounts/:account_id/features[](#post-accounts-account-id-features "Permalink to this headline") - -**SANDBOX ONLY** - -Add a feature to a sandbox account. - -The up to date list of account features may be retrieved via the [GET accounts/:account_id/features](#get-accounts-account-id-features) endpoint. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api-sandbox.x.com/12/accounts/:account_id/features` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `gq180y` | -| feature_keys
_required_ | A comma-separated list of account features to add to the account.

Type: enum

Possible values: `AGE_TARGETING`, `ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE`, `AWARENESS_OBJECTIVE`, `BRAND_TPN`, `CHARGE_FOR_GOOD_CLICK`, `CONVERSATION_CARD`, `CONVERSATION_CARD_FOUR_OPTIONS`, `CONVERSATION_CARD_UNLOCK`, `CPI_CHARGING`, `DIRECT_MESSAGE_CARD`, `DR_TAP`, `ENGAGER_RETARGETING`, `EVENT_TARGETING`, `INSTALLED_APP_CATEGORY_TARGETING`, `MOBILE_CONVERSION_TRANSACTION_VALUE`, `OPTIMIZED_ACTION_BIDDING`, `REACH_AND_FREQUENCY_ANALYTICS`, `REACH_FREQUENCY_CAP`, `VALIDATED_AGE_TARGETING`, `VIDEO_VIEWS_MIDROLL_OBJECTIVE`, `PREROLL_VIEWS_OBJECTIVE`, `VIDEO_APP_DOWNLOAD_CARD` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "gq180y", - "feature_keys": [ - "VALIDATED_AGE_TARGETING" - ] - } - }, - "data": [ - "ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE", - "AWARENESS_OBJECTIVE", - "CPI_CHARGING", - "EVENT_TARGETING", - "INSTALLED_APP_CATEGORY_TARGETING", - "MOBILE_CONVERSION_TRANSACTION_VALUE", - "OPTIMIZED_ACTION_BIDDING", - "VALIDATED_AGE_TARGETING", - "VIDEO_APP_DOWNLOAD_CARD" - ] - } -``` - -#### DELETE accounts/:account_id/features[](#delete-accounts-account-id-features "Permalink to this headline") - -**SANDBOX ONLY** - -Remove a feature from a sandbox account. - -The up to date list of account features may be retrieved via the [GET accounts/:account_id/features](#get-accounts-account-id-features) endpoint. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api-sandbox.x.com/12/accounts/:account_id/features` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `gq180y` | -| feature_keys
_required_ | A comma-separated list of account features to remove from the account.

Type: enum

Possible values: `AGE_TARGETING`, `ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE`, `AWARENESS_OBJECTIVE`, `BRAND_TPN`, `CHARGE_FOR_GOOD_CLICK`, `CONVERSATION_CARD`, `CONVERSATION_CARD_FOUR_OPTIONS`, `CONVERSATION_CARD_UNLOCK`, `CPI_CHARGING`, `DIRECT_MESSAGE_CARD`, `DR_TAP`, `ENGAGER_RETARGETING`, `EVENT_TARGETING`, `INSTALLED_APP_CATEGORY_TARGETING`, `MOBILE_CONVERSION_TRANSACTION_VALUE`, `OPTIMIZED_ACTION_BIDDING`, `REACH_AND_FREQUENCY_ANALYTICS`, `REACH_FREQUENCY_CAP`, `VALIDATED_AGE_TARGETING`, `VIDEO_VIEWS_MIDROLL_OBJECTIVE`, `PREROLL_VIEWS_OBJECTIVE`, `VIDEO_APP_DOWNLOAD_CARD` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "gq180y", - "feature_keys": [ - "PREROLL_VIEWS_OBJECTIVE" - ] - } - }, - "data": [ - "CPI_CHARGING", - "EVENT_TARGETING", - "INSTALLED_APP_CATEGORY_TARGETING", - "MOBILE_CONVERSION_TRANSACTION_VALUE", - "OPTIMIZED_ACTION_BIDDING", - "VIDEO_APP_DOWNLOAD_CARD" - ] - } -``` -### Funding Instruments - - -#### GET accounts/:account\_id/funding\_instruments[](#get-accounts-account-id-funding-instruments "Permalink to this headline") - -Retrieve details for some or all funding instruments associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/funding_instruments` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| funding\_instrument\_ids
_optional_ | Scope the response to just the desired 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](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t" - } - }, - "next_cursor": null, - "data": [ - { - "start_time": "2016-07-22T04:24:04Z", - "description": "Visa ending in 0650", - "credit_limit_local_micro": 200000000, - "end_time": null, - "id": "lygyi", - "entity_status": "ACTIVE", - "account_id": "18ce54d4x5t", - "reasons_not_able_to_fund": [], - "io_header": null, - "currency": "USD", - "funded_amount_local_micro": 645940000, - "created_at": "2016-07-22T04:24:04Z", - "type": "CREDIT_CARD", - "able_to_fund": true, - "updated_at": "2017-04-05T00:25:13Z", - "credit_remaining_local_micro": null, - "deleted": false - } - ] - } -``` - -#### GET accounts/:account\_id/funding\_instruments/:funding\_instrument\_id[](#get-accounts-account-id-funding-instruments-funding-instrument-id "Permalink to this headline") - -Retrieve a specific funding instrument associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/funding_instruments/:id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| funding\_instrument\_id
_required_ | A reference to the funding instrument you are operating with in the request.

Type: string

Example: `lygyi` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "funding_instrument_id": "lygyi", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "start_time": "2016-07-22T04:24:04Z", - "description": "Visa ending in 0650", - "credit_limit_local_micro": 200000000, - "end_time": null, - "id": "lygyi", - "entity_status": "ACTIVE", - "account_id": "18ce54d4x5t", - "reasons_not_able_to_fund": [], - "io_header": null, - "currency": "USD", - "funded_amount_local_micro": 645940000, - "created_at": "2016-07-22T04:24:04Z", - "type": "CREDIT_CARD", - "able_to_fund": true, - "updated_at": "2017-04-05T00:25:13Z", - "credit_remaining_local_micro": null, - "deleted": false - } - } -``` - -#### POST accounts/:account\_id/funding\_instruments[](#post-accounts-account-id-funding-instruments "Permalink to this headline") - -**SANDBOX ONLY** - -Create a funding instrument in the sandbox environment. - -There is no risk of incurring costs while using a sandbox funding instrument. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `gq1844` | -| currency
_required_ | The currency, expressed in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217).

Type: string

Example: `USD` | -| start_time
_required_ | The date for the funding instrument to become active and usable, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

Type: string

Example: `2017-05-19T07:00:00Z` | -| type
_required_ | The type of funding instrument to create.

Type: enum

Possible values: `AGENCY_CREDIT_LINE`, `CREDIT_CARD`, `CREDIT_LINE`, `INSERTION_ORDER`, `PARTNER_MANAGED` | -| end_time
_sometimes required_ | The date for the funding instrument to become inactive, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

Type: string

Example: `2017-05-26T07:00:00Z` | -| credit\_limit\_local_micro
_optional_ | The total credit available against this funding instrument.

**Note**: Only applicable to some funding instrument types.

Type: long

Example: `37500000` | -| funded\_amount\_local_micro
_optional_ | The total budget amount allocated to this funding instrument.

**Note**: Only applicable to some funding instrument types.

Type: long

Example: `37500000` | - -**Example Request[](#example-request "Permalink to this headline")** - -`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` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "start_time": "2017-07-10T00:00:00Z", - "description": "(no payment method has been set up yet)", - "credit_limit_local_micro": null, - "end_time": "2018-01-10T00:00:00Z", - "id": "hxtet", - "entity_status": "ACTIVE", - "account_id": "gq1844", - "reasons_not_able_to_fund": [], - "io_header": null, - "currency": "USD", - "funded_amount_local_micro": 140000000000, - "created_at": "2017-09-09T05:23:28Z", - "type": "INSERTION_ORDER", - "able_to_fund": true, - "updated_at": "2017-09-09T05:23:28Z", - "credit_remaining_local_micro": null, - "deleted": false - }, - "request": { - "params": { - "start_time": "2017-07-10T00:00:00Z", - "end_time": "2018-01-10T00:00:00Z", - "account_id": "gq1844", - "currency": "USD", - "funded_amount_local_micro": 140000000000, - "type": "INSERTION_ORDER" - } - } - } -``` - -#### DELETE accounts/:account\_id/funding\_instruments/:funding\_instrument\_id[](#delete-accounts-account-id-funding-instruments-funding-instrument-id "Permalink to this headline") - -**SANDBOX ONLY** - -Delete a funding instrument in the sandbox environment. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `gq1844` | -| funding\_instrument\_id
_required_ | A reference to the funding instrument you are operating with in the request.

Type: string

Exampple: `hxt82` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "start_time": "2017-08-30T19:23:47Z", - "description": "(no payment method has been set up yet)", - "credit_limit_local_micro": 500000000, - "end_time": null, - "id": "hxt82", - "entity_status": "ACTIVE", - "account_id": "gq1844", - "reasons_not_able_to_fund": [ - "DELETED" - ], - "io_header": null, - "currency": "USD", - "funded_amount_local_micro": null, - "created_at": "2017-08-30T19:23:47Z", - "type": "CREDIT_CARD", - "able_to_fund": false, - "updated_at": "2017-09-09T02:08:30Z", - "credit_remaining_local_micro": null, - "deleted": true - }, - "request": { - "params": { - "funding_instrument_id": "hxt82", - "account_id": "gq1844" - } - } - } -``` -### IAB Categories - - -#### GET iab_categories[](#get-iab-categories "Permalink to this headline") - -Request the valid app `categories` for ad groups (`line_items`). - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/iab_categories` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| 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 categories. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `gc-ddf4a` | -| 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/iab_categories?count=2` - -**Example Response[](#example-response "Permalink to this headline")** - -```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 - } - } - } -``` -### Line Items - - -#### GET accounts/:account\_id/line\_items[](#get-accounts-account-id-line-items "Permalink to this headline") - -Retrieve details for some or all line items associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_items` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#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 line items under specific campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8gdx6` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| funding\_instrument\_ids
_optional_ | Scope the response to just the line items under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `lygyi` | -| line\_item\_ids
_optional_ | Scope the response to just the desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8v7jo` | -| 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "line_item_ids": [ - "itttx" - ] - } - }, - "next_cursor": null, - "data": [ - { - "advertiser_user_id": "756201191646691328", - "name": "li-18", - "placements": [ - "ALL_ON_TWITTER" - ], - "start_time": "2021-02-16T00:00:00Z", - "bid_amount_local_micro": 320000, - "advertiser_domain": null, - "target_cpa_local_micro": null, - "primary_web_event_tag": null, - "goal": "ENGAGEMENT", - "daily_budget_amount_local_micro": null, - "product_type": "PROMOTED_TWEETS", - "end_time": null, - "funding_instrument_id": "lygyi", - "bid_strategy": "MAX", - "duration_in_days": null, - "standard_delivery": null, - "total_budget_amount_local_micro": null, - "objective": "ENGAGEMENTS", - "id": "itttx", - "entity_status": "PAUSED", - "automatic_tweet_promotion": null, - "frequency_cap": null, - "android_app_store_identifier": null, - "categories": [], - "currency": "USD", - "pay_by": "ENGAGEMENT", - "created_at": "2021-02-23T23:37:54Z", - "ios_app_store_identifier": null, - "updated_at": "2022-06-01T02:01:18Z", - "campaign_id": "f4z6x", - "creative_source": "MANUAL", - "deleted": false - } - ] - } -``` - -#### GET accounts/:account\_id/line\_items/:line\_item\_id[](#get-accounts-account-id-line-items-line-item-id "Permalink to this headline") - -Retrieve a specific line item associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "line_item_id": "itttx", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "advertiser_user_id": "756201191646691328", - "name": "li-18", - "placements": [ - "ALL_ON_TWITTER" - ], - "start_time": "2021-02-16T00:00:00Z", - "bid_amount_local_micro": 320000, - "advertiser_domain": null, - "target_cpa_local_micro": null, - "primary_web_event_tag": null, - "goal": "ENGAGEMENT", - "daily_budget_amount_local_micro": null, - "product_type": "PROMOTED_TWEETS", - "end_time": null, - "funding_instrument_id": "lygyi", - "bid_strategy": "MAX", - "duration_in_days": null, - "standard_delivery": null, - "total_budget_amount_local_micro": null, - "objective": "ENGAGEMENTS", - "id": "itttx", - "entity_status": "PAUSED", - "automatic_tweet_promotion": null, - "frequency_cap": null, - "android_app_store_identifier": null, - "categories": [], - "currency": "USD", - "pay_by": "ENGAGEMENT", - "created_at": "2021-02-23T23:37:54Z", - "ios_app_store_identifier": null, - "updated_at": "2022-06-01T02:01:18Z", - "campaign_id": "f4z6x", - "creative_source": "MANUAL", - "deleted": false - } - } -``` - -#### POST accounts/:account\_id/line\_items[](#post-accounts-account-id-line-items "Permalink to this headline") - -Create a line item associated with the specified campaign belonging to the current account. - -All line items within a campaign must be of the same `product_type` and `objective`. - -When using the `PROMOTED_ACCOUNT` product type, associating a Tweet with the `line_item` will add timeline placements on mobile in addition to the standard `PROMOTED_ACCOUNT` placement. - -Setting either `android_app_store_identifier` or `ios_app_store_identifier` will automatically add the targeting criteria for the line item matching the mobile app being promoted; for example, passing in `ios_app_store_identifier` would add `PLATFORM` [targeting criteria](/x-ads-api/campaign-management#targeting-options) for `iOS`. - -**Note**: There is a limit of 100 line items per campaign and 256 active line items across all campaigns. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_items` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| campaign_id
_required_ | The identifier for the campaign to create the line item under.

Type: string

Example: `8slvg` | -| end_time
_required_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will stop serving.

Type: string

Example: `2017-10-05T00:00:00Z` | -| objective
_required_ | The campaign objective for this line item.

Type: enum

Possible values: `APP_ENGAGEMENTS`, `APP_INSTALLS`, `REACH`, `FOLLOWERS`, `ENGAGEMENTS`, `VIDEO_VIEWS`, `PREROLL_VIEWS`, `WEBSITE_CLICKS` | -| placements
_required_ | The placement location(s) for this line item to display in. Specify a comma-separated list of placement values.

Type: enum

Possible values: `ALL_ON_TWITTER`, `PUBLISHER_NETWORK`, `TAP_BANNER`, `TAP_FULL`, `TAP_FULL_LANDSCAPE`, `TAP_NATIVE`, `TAP_MRECT`,`TWITTER_PROFILE`, `TWITTER_REPLIES`, `TWITTER_SEARCH`, `TWITTER_TIMELINE` | -| product_type
_required_ | The type of promoted product that this line item will contain.

Type: enum

Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS` | -| start_time
_required_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.

Type: string

Example: `2017-07-05T00:00:00Z` | -| advertiser_domain
_sometimes required_ | The website domain for this advertiser, without the protocol specification.

**Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.

Type: string

Example: `x.com` | -| android\_app\_store_identifier
_sometimes required_ | The Google App Store identifier for promoted applications.

**Note**: `APP_INSTALLS` and `APP_ENGAGEMENTS` objectives require setting at least one app store identifier -- either `android_app_store_identifier` or `ios_app_store_identifier`.

Type: string

Example: `com.twitter.android` | -| bid\_amount\_local_micro
_sometimes required_ | The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000.

**Note**: Required if `bid_strategy` is set to either `MAX` or `TARGET`

**Note**: Only values greater than zero are accepted.

Type: long

Example: `5500000` | -| categories
_sometimes required_ | The relevant IAB categories for this advertiser. See [GET iab_categories](/x-ads-api/campaign-management#iab-categories).

**Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.

Type: string

Example: `IAB3-1` | -| ios\_app\_store_identifier
_sometimes required_ | The numeric portion of the Apple App Store identifier for promoted applications.

**Note**: `APP_INSTALLS` and `APP_ENGAGEMENTS` objectives require setting at least one app store identifier -- either `android_app_store_identifier` or `ios_app_store_identifier`.

Type: string

Example: `333903271` | -| primary\_web\_event_tag
_sometimes required_ | The identifier of the primary web event tag. Allows more accurate tracking of engagements for the campaign pertaining to this line item.

**Note**: Required when the line item's goal is set to `WEBSITE_CONVERSIONS`.

Type: string

Example: `nvo4z` | -| advertiser\_user\_id
_optional_ | The X user identifier for the handle promoting a `PREROLL_VIEWS` ad. Only certain client applications may use this parameter.

Type: string

Example: `312226591` | -| audience_expansion
_optional_ | Used to expand the reach of campaigns by targeting users similar to those already targeted.

**Note**: By default, no expansion will be applied.

Type: enum

Possible values: `BROAD`, `DEFINED`, `EXPANDED` | -| bid_strategy
_optional_ | The bidding mechanism.

`AUTO` automatically optimizes bidding based on daily budget and campaign flight dates.

`MAX` sets the maximum allowable bid and is **not** available when the objective is set to `REACH` or `FOLLOWERS`.

`TARGET` attempts to make daily bid averages within 20% of the specified `bid_amount_local_micro` and is available when the objective is set to `REACH`, `FOLLOWERS`, OR `WEBSITE_CLICKS`.

**Note**: If set to `AUTO`, `bid_amount_local_micro` will be ignored.

**Note**: Default based on objective.

Type: enum

Possible values: `AUTO`, `MAX`, `TARGET` | -| duration\_in\_days
_optional_ | The time period within which the `frequency_cap` is achieved.

Type: int

Possible values: `1`, `7`, `30` | -| entity_status
_optional_ | The line item 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 `REACH`, `ENGAGEMENTS`, `VIDEO_VIEWS`, and `PREROLL_VIEWS` objectives.

Type: int

Example: `5` | -| goal
_optional_ | The optimization setting to use with this line item.

The `APP_PURCHASES` option is available for `APP_INSTALL`. The `APP_CLICKS` and `APP_INSTALLS` options are available for both `APP_INSTALL` and `APP_ENGAGEMENTS` objectives and may require using a supported [MACT partner](https://business.x.com/en/help/campaign-setup/create-an-app-installs-or-app-engagement-campaign/mobile-app-conversion-tracking.html).

The `SITE_VISITS` option is only available with the `WEBSITE_CLICKS` objective.

**Note**: Default based on objective.

Type: enum

Possible values: `APP_CLICKS`, `APP_INSTALLS`, `APP_PURCHASES`,`ENGAGEMENT`, `FOLLOWERS`, `LINK_CLICKS`, `MAX_REACH`, `PREROLL`, `PREROLL_STARTS`, `REACH_WITH_ENGAGEMENT`, `SITE_VISITS`, `VIDEO_VIEW`, `VIEW_3S_100PCT`, `VIEW_6S`, `VIEW_15S`, `WEBSITE_CONVERSIONS` | -| name
_optional_ | The name for the line item.

Type: string

Example: `demo`

Min, Max length: `1`, `255` | -| pay_by
_optional_ | The unit to charge this line item by. This setting can only be modified for line items using the `APP_INSTALLS` objective.

**Note**: The default `pay_by` is automatically set based upon the campaign objective and line item's bid unit.

The `APP_INSTALLS` goal supports both `APP_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value.

The `LINK_CLICKS` goal supports both `LINK_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value but is not supported when setting `TARGET` for `bid_strategy`.

The `SITE_VISITS` goal supports `IMPRESSION` values.

Type: enum

Possible values: `APP_CLICK`, `IMPRESSION`, `LINK_CLICK` | -| standard_delivery
_optional_ | Enable standard or accelerated delivery. See [Budget Pacing](/x-ads-api/campaign-management#budget-pacing) for more information on standard versus accelerated delivery. Only available when `budget_optimization` is set to `LINE_ITEM` for the parent campaign

Type: boolean

Default: `true`
Possible values: `true`, `false` | -| total\_budget\_amount\_local\_micro
_optional_ | The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000.

Type: long

Example: `37500000` | -| 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. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Only available when `budget_optimization` is set to `LINE_ITEM` for the parent campaign

**Note**: This should be less than or equal to the `total_budget_amount_local_micro`.

Type: long

Example: `5500000` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?campaign_id=hwtq0&objective=ENGAGEMENTS&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&bid_amount_local_micro=3210000&entity_status=PAUSED&daily_budget_amount_local_micro=1000000&start_time=2022-06-15` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "placements": [ - "ALL_ON_TWITTER" - ], - "start_time": "2022-06-15T00:00:00Z", - "bid_amount_local_micro": 3210000, - "daily_budget_amount_local_micro": 1000000, - "product_type": "PROMOTED_TWEETS", - "objective": "ENGAGEMENTS", - "entity_status": "PAUSED", - "account_id": "18ce54d4x5t", - "campaign_id": "hwtq0" - } - }, - "data": { - "advertiser_user_id": "756201191646691328", - "name": null, - "placements": [ - "ALL_ON_TWITTER" - ], - "start_time": "2022-06-15T00:00:00Z", - "bid_amount_local_micro": 3210000, - "advertiser_domain": null, - "target_cpa_local_micro": null, - "primary_web_event_tag": null, - "goal": "ENGAGEMENT", - "daily_budget_amount_local_micro": 1000000, - "product_type": "PROMOTED_TWEETS", - "end_time": null, - "bid_strategy": "MAX", - "duration_in_days": null, - "standard_delivery": true, - "total_budget_amount_local_micro": null, - "objective": "ENGAGEMENTS", - "id": "ml5vs", - "entity_status": "PAUSED", - "automatic_tweet_promotion": null, - "frequency_cap": null, - "android_app_store_identifier": null, - "categories": [], - "currency": "USD", - "pay_by": "ENGAGEMENT", - "created_at": "2022-06-03T23:47:20Z", - "ios_app_store_identifier": null, - "updated_at": "2022-06-03T23:47:20Z", - "campaign_id": "hwtq0", - "creative_source": "MANUAL", - "deleted": false - } - } -``` - -#### POST batch/accounts/:account\_id/line\_items[](#post-batch-accounts-account-id-line-items "Permalink to this headline") - -Allows the batch creation of new [line items](#post-accounts-account-id-line-items) 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 line item parameter) are shown in the response under the `operation_errors` object. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/batch/accounts/:account_id/line_items` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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 line item objects. For a list of required and optional line item parameters, see [here](#post-accounts-account-id-line-items). | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items` - -```json - [ - { - "operation_type":"Create", - "params":{ - "campaign_id":"8yn7m", - "objective":"ENGAGEMENTS", - "product_type":"PROMOTED_TWEETS", - "placements":"ALL_ON_TWITTER", - "bid_amount_local_micro":3210000, - "entity_status":"PAUSED" - } - } - ] -``` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "advertiser_user_id": "756201191646691328", - "name": null, - "placements": [ - "ALL_ON_TWITTER" - ], - "start_time": null, - "bid_amount_local_micro": 3210000, - "advertiser_domain": null, - "target_cpa_local_micro": null, - "primary_web_event_tag": null, - "goal": "ENGAGEMENT", - "daily_budget_amount_local_micro": null, - "product_type": "PROMOTED_TWEETS", - "end_time": null, - "funding_instrument_id": "lygyi", - "bid_strategy": "MAX", - "duration_in_days": null, - "standard_delivery": null, - "total_budget_amount_local_micro": null, - "objective": "ENGAGEMENTS", - "id": "9cqi0", - "entity_status": "PAUSED", - "automatic_tweet_promotion": null, - "frequency_cap": null, - "android_app_store_identifier": null, - "categories": [], - "currency": "USD", - "pay_by": "ENGAGEMENT", - "created_at": "2017-07-07T17:42:20Z", - "ios_app_store_identifier": null, - "updated_at": "2017-07-07T17:42:20Z", - "campaign_id": "8yn7m", - "creative_source": "MANUAL", - "deleted": false - } - ], - "request": [ - { - "params": { - "placements": [ - "ALL_ON_TWITTER" - ], - "bid_amount_local_micro": 3210000, - "product_type": "PROMOTED_TWEETS", - "objective": "ENGAGEMENTS", - "entity_status": "PAUSED", - "account_id": "18ce54d4x5t", - "campaign_id": "8yn7m" - }, - "operation_type": "Create" - } - ] - } -``` - -#### PUT accounts/:account\_id/line\_items/:line\_item\_id[](#put-accounts-account-id-line-items-line-item-id "Permalink to this headline") - -Update the specified line item associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | -| advertiser_domain
_optional_ | The website domain for this advertiser, without the protocol specification.

**Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.

Type: string

Example: `x.com` | -| advertiser\_user\_id
_optional_ | The Twitter user identifier for the handle promoting a `PREROLL_VIEWS` ad. Only certain client applications may use this parameter.

Type: string

Example: `312226591` | -| android\_app\_store_identifier
_optional_ | The Google App Store identifier for the promoted application.

**Note**: `APP_INSTALLS` and `APP_ENGAGEMENTS` objectives require setting at least one app store identifier -- either `android_app_store_identifier` or `ios_app_store_identifier`.

Type: string

Example: `com.twitter.android` | -| audience_expansion
_optional_ | Used to expand the reach of campaigns by targeting users similar to those already targeted.

Type: enum

Possible values: `BROAD`, `DEFINED`, `EXPANDED` | -| bid\_amount\_local_micro
_optional_ | The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000.

**Note**: Required if `bid_strategy` is set to either `MAX` or `TARGET`

**Note**: Only values greater than zero are accepted.

Type: long

Example: `140000` | -| bid_strategy
_optional_ | The bidding mechanism.

`AUTO` automatically optimizes bidding based on daily budget and campaign flight dates.

`MAX` sets the maximum allowable bid and is **not** available when the objective is set to `REACH` or `FOLLOWERS`.

`TARGET` attempts to make daily bid averages within 20% of the specified `bid_amount_local_micro` and is available when the objective is set to `REACH` or `WEBSITE_CLICKS`.

**Note**: If set to `AUTO`, `bid_amount_local_micro` will be ignored.

**Note**: Default based on objective.

Type: enum

Possible values: `AUTO`, `MAX`, `TARGET` | -| categories
_optional_ | The relevant IAB categories for this advertiser. See [GET iab_categories](/x-ads-api/campaign-management#iab-categories).

**Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.

Type: string

Example: `IAB3-1` | -| duration\_in\_days
_optional_ | The time period within which the `frequency_cap` is achieved.

Type: int

Possible values: `1`, `7`, `30` | -| entity_status
_optional_ | The line item status.

Type: enum

Possible values: `ACTIVE`, `PAUSED` | -| end_time
_optional_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will stop serving.

Type: string

Example: `2017-10-05T00:00:00Z` | -| frequency_cap
_optional_ | The maximum number of times an ad could be delivered to a user.

**Note**: Only supported for `REACH`, `ENGAGEMENTS`, `VIDEO_VIEWS`, and `PREROLL_VIEWS` objectives.

Type: int

Example: `5` | -| goal
_optional_ | The optimization setting to use with this line item. The `APP_PURCHASES` option is available for `APP_INSTALL`. The `APP_CLICKS` and `APP_INSTALLS` options are available for `APP_INSTALL` and `APP_ENGAGEMENTS` and may require using a supported [MACT partner](https://business.x.com/en/help/campaign-setup/create-an-app-installs-or-app-engagement-campaign/mobile-app-conversion-tracking.html).

**Note**: Default based on objective.

Type: enum

Possible values: `APP_CLICKS`, `APP_INSTALLS`, `APP_PURCHASES`, `ENGAGEMENT`, `FOLLOWERS`, `LINK_CLICKS`, `MAX_REACH`, `PREROLL`, `PREROLL_STARTS`, `REACH_WITH_ENGAGEMENT`, `VIDEO_VIEW`, `VIEW_3S_100PCT`, `VIEW_6S`, `VIEW_15S`, `WEBSITE_CONVERSIONS` | -| ios\_app\_store_identifier
_optional_ | The numeric portion of the Apple App Store identifier for promoted applications.

**Note**: `APP_INSTALLS` and `APP_ENGAGEMENTS` objectives require setting at least one app store identifier -- either `android_app_store_identifier` or `ios_app_store_identifier`.

Type: string

Example: `333903271` | -| name
_optional_ | The name for the line item.

Type: string

Example: `demo` | -| pay_by
_optional_ | The unit to charge this line item by. This setting can only be modified for line items using the `APP_INSTALLS` objective.

**Note**: The default `pay_by` is automatically set based upon the campaign objective and line item's bid unit.

The `APP_INSTALLS` goal supports both `APP_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value.

The `LINK_CLICKS` goal supports both `LINK_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value but is not supported when setting `TARGET` for `bid_strategy`.

The `SITE_VISITS` goal supports `IMPRESSION` values.

Type: enum

Possible values: `APP_CLICK`, `IMPRESSION`, `LINK_CLICK` | -| start_time
_optional_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.

Type: string

Example: `2017-07-05T00:00:00Z` | -| total\_budget\_amount\_local\_micro
_optional_ | The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000.

Type: long

Example: `37500000` | -| 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. Only available when `budget_optimization` is set to `LINE_ITEM` for the parent campaign

**Note**: This should be less than or equal to the `total_budget_amount_local_micro`.

Type: long

Example: `5500000` | - -**Example Request[](#example-request "Permalink to this headline")** - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "line_item_id": "9cqi0", - "bid_amount_local_micro": 140000, - "account_id": "18ce54d4x5t" - } - }, - "data": { - "advertiser_user_id": "756201191646691328", - "name": null, - "placements": [ - "ALL_ON_TWITTER" - ], - "start_time": "2017-07-10T00:00:00Z", - "bid_amount_local_micro": 140000, - "advertiser_domain": null, - "target_cpa_local_micro": null, - "primary_web_event_tag": null, - "goal": "ENGAGEMENT", - "daily_budget_amount_local_micro": null, - "product_type": "PROMOTED_TWEETS", - "end_time": null, - "bid_strategy": "MAX", - "duration_in_days": null, - "standard_delivery": null, - "total_budget_amount_local_micro": null, - "objective": "ENGAGEMENTS", - "id": "9cqi0", - "entity_status": "PAUSED", - "automatic_tweet_promotion": null, - "frequency_cap": null, - "android_app_store_identifier": null, - "categories": [], - "currency": "USD", - "pay_by": "ENGAGEMENT", - "created_at": "2017-07-07T17:42:20Z", - "ios_app_store_identifier": null, - "updated_at": "2022-06-03T23:51:36Z", - "campaign_id": "8yn7m", - "creative_source": "MANUAL", - "deleted": false - } - } -``` - -#### DELETE accounts/:account\_id/line\_items/:line\_item\_id[](#delete-accounts-account-id-line-items-line-item-id "Permalink to this headline") - -Delete the specified line item belonging to the current account. - -**Note**: Deleting a line item is not reversible and subsequent attempts to delete the resource will return HTTP 404. - -**Note**: When a line item is deleted, its child promoted\_tweets are only returned in the GET accounts/:account\_id/promoted\_tweets and GET accounts/:account\_id/promoted\_tweets/:promoted\_tweet_id endpoints if `with_deleted=true` is specified in the request. These promoted_tweets are not actually deleted, though (`"deleted": false` in the response). We do not cascade deletes. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Exampple: `9f2ix` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "bid_strategy": "MAX", - "advertiser_user_id": "756201191646691328", - "name": "Untitled", - "placements": [], - "start_time": null, - "bid_amount_local_micro": 100000, - "advertiser_domain": null, - "target_cpa_local_micro": null, - "primary_web_event_tag": null, - "pay_by": "ENGAGEMENT", - "product_type": "PROMOTED_TWEETS", - "end_time": "2017-07-21T00:00:00Z", - "duration_in_days": 1, - "total_budget_amount_local_micro": null, - "objective": "ENGAGEMENTS", - "id": "9f2ix", - "entity_status": "ACTIVE", - "goal": "ENGAGEMENT", - "frequency_cap": 5, - "categories": [], - "currency": "USD", - "created_at": "2017-07-14T00:01:50Z", - "updated_at": "2017-08-09T07:41:08Z", - "campaign_id": "90r8n", - "creative_source": "MANUAL", - "deleted": true - }, - "request": { - "params": { - "line_item_id": "9f2ix", - "account_id": "18ce54d4x5t" - } - } - } -``` -### Line Item Curated Categories - - -Additional details on usage can be found at the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective) - -#### GET accounts/:account\_id/line\_item\_curated\_categories[](#get-accounts-account-id-line-item-curated-categories "Permalink to this headline") - -Retrieve details for some or all line item curated categories associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories` - -**Example Response[](#example-response "Permalink to this headline")** - -```josn - { - "request": { - "params": { - "account_id": "abc1" - } - }, - "next_cursor": null, - "data": [ - { - "line_item_id": "by5pw", - "curated_category_id": "7op29tp2jzeo", - "id": "1", - "created_at": "2018-06-29T04:19:53Z", - "updated_at": "2018-06-29T04:19:53Z", - "deleted": false - } - ] - } -``` - -#### GET accounts/:account\_id/line\_item\_curated\_categories/:line\_item\_curated\_category\_id[](#get-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline") - -Retrieves details for a specific line item curated category associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_curated\_category\_id
_required_ | A reference to the line item curated category you are operating with in the request.

Type: string

Example: `43853bhii885` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "line_item_curated_category_id": "yav", - "account_id": "abc1" - } - }, - "data": { - "line_item_id": "by5pw", - "curated_category_id": "7op29tp2jzeo", - "id": "yav", - "created_at": "2018-06-29T04:19:53Z", - "updated_at": "2018-06-29T04:19:53Z", - "deleted": false - } - } -``` - -#### POST accounts/:account\_id/line\_item\_curated\_categories[](#post-accounts-account-id-line-item-curated-categories "Permalink to this headline") - -Associate a [curated category](/x-ads-api/campaign-management#curated-categories-2) object with the specified line item. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| curated\_category\_id
`required` | A reference to the curated category entity you are operating with in the request.

Type: string

Example: `10miy` | -| line\_item\_id
`required` | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "curated_category_id": "9ddrgesiap6o", - "line_item_id": "iqwka", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "line_item_id": "iqwka", - "curated_category_id": "9ddrgesiap6o", - "id": "xq", - "created_at": "2021-03-30T17:26:42Z", - "updated_at": "2021-03-30T17:26:42Z", - "deleted": false - } - } -``` - -#### PUT accounts/:account\_id/line\_item\_curated\_categories/:line\_item\_curated\_category\_id[](#put-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline") - -Update the specified line item curated category. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_curated\_category\_id
_required_ | A reference to the line item curated category you are operating with in the request.

Type: string

Example: `1bzq3` | -| curated\_category\_id
`optional` | A reference to the curated category entity you are operating with in the request.

Type: string

Example: `10miy` | -| line\_item\_id
`optional` | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | - -**Example Request[](#example-request "Permalink to this headline")** - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "line_item_curated_category_id": "xq", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "line_item_id": "iqwka", - "curated_category_id": "8tujl1p3yn0g", - "id": "xq", - "created_at": "2021-03-30T17:26:42Z", - "updated_at": "2021-03-30T18:22:52Z", - "deleted": true - } - } -``` - -#### DELETE accounts/:account\_id/line\_item\_curated\_categories/:line\_item\_curated\_category\_id[](#delete-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline") - -Delete the specified line item curated category. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_curated\_category\_id
_required_ | A reference to the line item curated category you are operating with in the request.

Type: string

Example: `1bzq3` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "line_item_curated_category_id": "xq", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "line_item_id": "iqwka", - "curated_category_id": "9ddrgesiap6o", - "id": "xq", - "created_at": "2021-03-30T17:26:42Z", - "updated_at": "2021-03-30T18:22:52Z", - "deleted": true - } - } -``` -### Line Item Placements - - -#### GET line_items/placements[](#get-line-items-placements "Permalink to this headline") - -Retrieve valid `placement` and `product_type` combinations. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/line_items/placements` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| product_type
_optional_ | Scope the response to just the valid placements for the specified product type.

Type: enum

Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "product_type": "PROMOTED_ACCOUNT", - "placements": [ - [ - "ALL_ON_TWITTER" - ], - [ - "TWITTER_TIMELINE" - ] - ] - } - ], - "request": { - "params": { - "product_type": "PROMOTED_ACCOUNT" - } - } - } -``` -### Media Creatives - - -#### GET accounts/:account\_id/media\_creatives[](#get-accounts-account-id-media-creatives "Permalink to this headline") - -Retrieve details for some or all media creatives associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/media_creatives` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| campaign_id
_optional_ | Scope the response to just the media creatives associated with the specified campaign.

Type: string

Example: `8gdx6` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| line\_item\_ids
_optional_ | Scope the response to just the media creatives associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8v7jo` | -| media\_creative\_ids
_optional_ | Scope the response to just the desired media creatives by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `1bzq3` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "media_creative_ids": [ - "1bzq3" - ] - } - }, - "next_cursor": null, - "data": [ - { - "line_item_id": "8v7jo", - "landing_url": "https://dev.x.com", - "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", - "id": "1bzq3", - "entity_status": "ACTIVE", - "created_at": "2017-07-05T06:00:42Z", - "account_media_id": "10miy", - "updated_at": "2019-01-11T20:21:26Z", - "approval_status": "ACCEPTED", - "deleted": false - } - ] - } -``` - -#### GET accounts/:account\_id/media\_creatives/:media\_creative\_id[](#get-accounts-account-id-media-creatives-media-creative-id "Permalink to this headline") - -Retrieves details for a specific media creative associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| media\_creative\_id
_required_ | A reference to the media creative you are operating with in the request.

Type: string

Example: `43853bhii885` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "media_creative_id": "1bzq3", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "line_item_id": "8v7jo", - "landing_url": "https://dev.x.com", - "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", - "id": "1bzq3", - "entity_status": "ACTIVE", - "created_at": "2017-07-05T06:00:42Z", - "account_media_id": "10miy", - "updated_at": "2019-01-11T20:21:26Z", - "approval_status": "ACCEPTED", - "deleted": false - } - } -``` - -#### POST accounts/:account\_id/media\_creatives[](#post-accounts-account-id-media-creatives "Permalink to this headline") - -Associate an [account media](/x-ads-api/creatives#account-media) object with the specified line item. - -Use this endpoint to promote in-stream ads (when the account media `creative_type` is `PREROLL`) or image ads (such as `BANNER` or `INTERSTITIAL`) on the Twitter Audience Platform. - -**Note**: In order to add media assets to the Account Media resource, use the [POST accounts/:account\_id/media\_library](/x-ads-api/creatives#account-media) endpoint. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/media_creatives` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| account\_media\_id
`required` | A reference to the account media entity you are operating with in the request.

Type: string

Example: `10miy` | -| line\_item\_id
`required` | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | -| landing_url
`sometimes required` | The URL of the website to direct a user to. This should only be used with TAP images (or "display creatives"). This value will be ignored if used with preroll assets. To associate a URL with a preroll asset, use the [POST accounts/:account\_id/preroll\_call\_to\_actions](/x-ads-api/creatives#post-accounts-account-id-preroll-call-to-actions) endpoint.

**Note**: Required when the line item's objective is set to `WEBSITE_CLICKS`.

Type: string

Example: `https://blog.x.com/` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "line_item_id": "8v7jo", - "account_media_id": "10miy", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "line_item_id": "8v7jo", - "landing_url": "https://dev.x.com", - "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", - "id": "1bzq3", - "entity_status": "ACTIVE", - "created_at": "2017-07-05T06:00:42Z", - "account_media_id": "10miy", - "updated_at": "2019-01-11T20:21:26Z", - "approval_status": "ACCEPTED", - "deleted": false - } - } -``` - -#### DELETE accounts/:account\_id/media\_creatives/:media\_creative\_id[](#delete-accounts-account-id-media-creatives-media-creative-id "Permalink to this headline") - -Delete the specified media creative belonging to the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| media\_creative\_id
_required_ | A reference to the media creative you are operating with in the request.

Type: string

Example: `1bzq3` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "media_creative_id": "1bzq3", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "line_item_id": "8v7jo", - "landing_url": "https://dev.x.com", - "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", - "id": "1bzq3", - "entity_status": "ACTIVE", - "created_at": "2017-07-05T06:00:42Z", - "account_media_id": "10miy", - "updated_at": "2021-04-16T21:02:55Z", - "approval_status": "ACCEPTED", - "deleted": true - } - } -``` -### Promoted Accounts - - -#### GET accounts/:account\_id/promoted\_accounts[](#get-accounts-account-id-promoted-accounts "Permalink to this headline") - -Retrieve details for some or all promoted accounts associated with one or more line items under the current account. - -Use [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) to obtain user data for the user accounts identified by `user_id` in the response. - -An HTTP 400 will be returned if none of the specified line items are configured to contain promoted accounts. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promoted_accounts` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| line\_item\_ids
_optional_ | Scope the response to just the promoted accounts associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `9bpb2` | -| promoted\_account\_ids
_optional_ | Scope the response to just the desired promoted accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `19pl2` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2` - -**Example Response[](#example-response "Permalink to this headline")** - -```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 accounts/:account\_id/promoted\_accounts/:promoted\_account\_id[](#get-accounts-account-id-promoted-accounts-promoted-account-id "Permalink to this headline") - -Retrieve a specific reference to an account associated with a line item under the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| promoted\_account\_id
_required_ | A reference to the promoted account you are operating with in the request.

Type: string

Example: `19pl2` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "promoted_account_id": "19pl2", - "account_id": "18ce54d4x5t" - } - }, - "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 - } - } -``` - -#### POST accounts/:account\_id/promoted\_accounts[](#post-accounts-account-id-promoted-accounts "Permalink to this headline") - -Associate an account (`user_id`) with the specified line item. - -If the specified line item is not configured to be associated with Promoted Accounts, a HTTP 400 `INCOMPATIBLE_LINE_ITEM` error will be returned. If the specified user is ineligible for promotion, a HTTP 400 will be returned and no users will be promoted. If the provided user is already promoted, the request will be ignored. - -For more information on Promoted Accounts, see our [campaign management](/x-ads-api/campaign-management#advertiser-api) page. - -**Note**: It is not possible to update (PUT) promoted accounts entities. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promoted_accounts` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `9bpb2` | -| user_id
_required_ | A reference to the user you are operating with in the request. Use [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) to retrieve a user ID for a screen name.

Type: long

Example: `756201191646691328` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "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 - }, - "request": { - "params": { - "user_id": "756201191646691328", - "line_item_id": "9bpb2", - "account_id": "18ce54d4x5t" - } - } - } -``` - -#### DELETE accounts/:account\_id/promoted\_accounts/:promoted\_account\_id[](#delete-accounts-account-id-promoted-accounts-promoted-account-id "Permalink to this headline") - -Disassociate an account from the specified line item. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| promoted\_account\_id
_required_ | The identifier refers to the instance of a Promoted Account associated with a line item.

Type: string

Example: `19pl2` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "line_item_id": "9bpb2", - "user_id": "756201191646691328", - "id": "19pl2", - "entity_status": "ACTIVE", - "created_at": "2017-07-05T05:54:13Z", - "updated_at": "2017-08-23T18:53:15Z", - "approval_status": "ACCEPTED", - "deleted": true - }, - "request": { - "params": { - "promoted_account_id": "19pl2", - "account_id": "18ce54d4x5t" - } - } - } -``` -### Promoted Tweets - - -#### GET accounts/:account\_id/promoted\_tweets[](#get-accounts-account-id-promoted-tweets "Permalink to this headline") - -Retrieve references to Tweets associated with line items under the current account. - -Use the [GET accounts/:account_id/tweets](/x-ads-api/creatives#get-accounts-account-id-tweets) endpoint to fetch the Tweet objects. Use the `tweet_id` values for each promoted_tweets object. - -**Note**: When parent line items are deleted, promoted_tweets are only returned if `with_deleted=true` is specified in the request. These promoted_tweets are not actually deleted, though (`"deleted": false` in the response). - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promoted_tweets` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| line\_item\_ids
_optional_ | Scope the response to just the Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `96uzp` | -| promoted\_tweet\_ids
_optional_ | Scope the response to just the desired promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `1efwlo` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "promoted_tweet_ids": [ - "1efwlo" - ], - "account_id": "18ce54d4x5t" - } - }, - "next_cursor": null, - "data": [ - { - "line_item_id": "96uzp", - "id": "1efwlo", - "entity_status": "ACTIVE", - "created_at": "2017-06-29T05:06:57Z", - "updated_at": "2017-06-29T05:08:46Z", - "approval_status": "ACCEPTED", - "tweet_id": "880290790664060928", - "deleted": false - } - ] - } -``` - -#### GET accounts/:account\_id/promoted\_tweets/:promoted\_tweet\_id[](#get-accounts-account-id-promoted-tweets-promoted-tweet-id "Permalink to this headline") - -Retrieve a specific reference to a Tweet associated with a line item under the current account. - -**Note**: When parent line items are deleted, promoted_tweets are only returned if `with_deleted=true` is specified in the request. These promoted_tweets are not actually deleted, though (`"deleted": false` in the response). - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| promoted\_tweet\_id
_required_ | A reference to the promoted Tweet you are operating with in the request.

Type: string

Example: `1efwlo` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "promoted_tweet_id": "1efwlo", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "line_item_id": "96uzp", - "id": "1efwlo", - "entity_status": "ACTIVE", - "created_at": "2017-06-29T05:06:57Z", - "updated_at": "2017-06-29T05:08:46Z", - "approval_status": "ACCEPTED", - "tweet_id": "880290790664060928", - "deleted": false - } - } -``` - -#### POST accounts/:account\_id/promoted\_tweets[](#post-accounts-account-id-promoted-tweets "Permalink to this headline") - -Associate one or more Tweets with the specified line item. Not all Tweets are appropriate for promotion, depending on the campaign objective. Please see [Objective-based Campaigns](/x-ads-api/campaign-management#objective-based-campaigns) for more information. - -When using the `PROMOTED_ACCOUNT` product type, associating a Tweet with the `line_item` will add timeline placements on mobile in addition to the standard `PROMOTED_ACCOUNT` placement. - -**Note**: It is not possible to update (PUT) promoted Tweet entities. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promoted_tweets` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | -| tweet_ids
_required_ | A comma-separated list of identifiers corresponding to specific Tweets. Up to 50 IDs may be provided.

Type: long

Example: `822333526255120384` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "line_item_id": "8v7jo", - "id": "1e8i2k", - "entity_status": "ACTIVE", - "created_at": "2017-06-24T04:21:36Z", - "updated_at": "2017-06-24T04:21:36Z", - "approval_status": "ACCEPTED", - "tweet_id": "822333526255120384", - "deleted": false - } - ], - "request": { - "params": { - "line_item_id": "8v7jo", - "tweet_ids": [ - 822333526255120384 - ], - "account_id": "18ce54d4x5t" - } - }, - "total_count": 1 - } -``` - -#### DELETE accounts/:account\_id/promoted\_tweets/:promoted\_tweet\_id[](#delete-accounts-account-id-promoted-tweets-promoted-tweet-id "Permalink to this headline") - -Disassociate a Tweet from the specified line item. - -**Note**: A deleted promoted_tweets entity will be displayed as "Paused" in the ads.x.com UI. Similarly, "pausing" from the UI will disassociate the Tweet from its line item. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| promoted\_tweet\_id
_required_ | The identifier refers to the instance of a Promoted Tweet associated with a line item. This comes from the `id` field from a response item to [GET accounts/:account\_id/promoted\_tweets](#get-accounts-account-id-promoted-tweets), not the `tweet_id` of the Tweet in question. Supplied within the resource's path.

Type: string

Example: `1gp8a5` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "line_item_id": "9pl99", - "id": "1gp8a5", - "entity_status": "ACTIVE", - "created_at": "2017-08-17T17:02:21Z", - "updated_at": "2017-08-18T06:43:48Z", - "approval_status": "ACCEPTED", - "tweet_id": "844796297743757315", - "deleted": true - }, - "request": { - "params": { - "promoted_tweet_id": "1gp8a5", - "account_id": "18ce54d4x5t" - } - } - } -``` -### Promotable Users - - -#### GET accounts/:account\_id/promotable\_users[](#get-accounts-account-id-promotable-users "Permalink to this headline") - -Retrieve details for some or all promotable users associated with the current account. - -The promotable user type is either `FULL` or `RETWEETS_ONLY`. This controls the type of content that is allowed to be promoted by the account. Advertisers must obtain permission to promote another user's content and contact Twitter to get them added to your account as a `RETWEETS_ONLY` promotable user. - -Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you'd like to promote. You can use the [POST accounts/:account_id/promoted-tweets](/x-ads-api/campaign-management#promoted-tweets) endpoint to promote published Tweets and the [POST accounts/:account_id/scheduled-promoted-tweets](/x-ads-api/campaign-management#promoted-tweets) endpoint to promote another Twitter Ads account's Scheduled Tweets. - -You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the `tweet_id` that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The `tweet_id` that is returned corresponds to this new Tweet. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promotable_users` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| promotable\_user\_ids
_optional_ | Scope the response to just the desired promotable users by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `l310s` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s` - -**Example Response[](#example-response "Permalink to this headline")** - -```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" - } - ] - } -``` - -#### GET accounts/:account\_id/promotable\_users/:promotable\_user\_id[](#get-accounts-account-id-promotable-users-promotable-user-id "Permalink to this headline") - -Retrieve a specific promotable user associated with the current account. - -The promotable user type is either `FULL` or `RETWEETS_ONLY`. This controls the type of content that is allowed to be promoted by the account. - -Advertisers must obtain permission to promote another user's content. Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you'd like to promote. - -You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the `tweet_id` that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The `tweet_id` that is returned corresponds to this new Tweet. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/promotable_users/:promotable_user_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| promotable\_user\_id
_optional_ | A reference to the promotable user you are operating on within the request

Type: string

Example: `l310s` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "promotable_user_id": "l310s", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "user_id": "2417045708", - "id": "l310s", - "created_at": "2017-03-10T17:51:24Z", - "updated_at": "2017-03-10T17:51:24Z", - "deleted": false, - "promotable_user_type": "RETWEETS_ONLY" - } - } -``` -### Publishers - - -#### GET publishers[](#get-publishers "Permalink to this headline") - -Retrieve a list of Content Category publishers' details - -Additional details can be found in the [Video Views Preroll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective) - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/publishers` - -**Parameters[](#parameters "Permalink to this headline")** - -No request parameters - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/publishers` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": {} - }, - "next_cursor": null, - "data": [ - { - "monetizable_country_codes": [ - "US" - ], - "promotion_eligible_country_codes": [ - "US" - ], - "username": "PeoplesSports", - "user_id": "1353868435021721602", - "monetization_restricted": true, - "content_category_ids": [ - "se" - ] - }, - { - "monetizable_country_codes": [ - "JP" - ], - "promotion_eligible_country_codes": [ - "JP" - ], - "username": "NewYork_Jack", - "user_id": "1331177123436851206", - "monetization_restricted": true, - "content_category_ids": [ - "sk" - ] - }, - { - "monetizable_country_codes": [ - "JP" - ], - "promotion_eligible_country_codes": [ - "JP" - ], - "username": "twispatv", - "user_id": "1331165719128461314", - "monetization_restricted": true, - "content_category_ids": [ - "sm" - ] - }, - { - "monetizable_country_codes": [ - "US" - ], - "promotion_eligible_country_codes": [ - "US" - ], - "username": "LAThieves", - "user_id": "1316808678897455105", - "monetization_restricted": true, - "content_category_ids": [ - "s0" - ] - }, - { - "monetizable_country_codes": [ - "US" - ], - "promotion_eligible_country_codes": [ - "US" - ], - "username": "Quicktake_EE", - "user_id": "1305900477427724290", - "monetization_restricted": true, - "content_category_ids": [ - "sr" - ] - }, - { - "monetizable_country_codes": [ - "BR" - ], - "promotion_eligible_country_codes": [ - "BR" - ], - "username": "eufloribella", - "user_id": "1300812459054436354", - "monetization_restricted": true, - "content_category_ids": [ - "sm" - ] - }, - { - "monetizable_country_codes": [ - "EG" - ], - "promotion_eligible_country_codes": [ - "KW", - "EG", - "SA", - "AE", - "LB", - "QA" - ], - "username": "Egypt2021EN", - "user_id": "1296077573399678977", - "monetization_restricted": true, - "content_category_ids": [ - "se" - ] - }, - { - "monetizable_country_codes": [ - "US" - ], - "promotion_eligible_country_codes": [ - "US" - ], - "username": "ClubShayShay", - "user_id": "1283068366706454529", - "monetization_restricted": true, - "content_category_ids": [ - "se" - ] - }, - { - "monetizable_country_codes": [ - "IN", - "KW", - "ID", - "EG", - "SG", - "TH", - "MY", - "PH", - "ES", - "US", - "AU", - "SA", - "AE", - "LB", - "GB", - "FR", - "KR", - "BR", - "MX", - "QA", - "CA", - "JP" - ], - "promotion_eligible_country_codes": [ - "KW", - "EG", - "SA", - "AE", - "LB", - "QA" - ], - "username": "hiaahsanshow", - "user_id": "1253421442143641601", - "monetization_restricted": false, - "content_category_ids": [ - "sh" - ] - }, - { - "monetizable_country_codes": [ - "TH" - ], - "promotion_eligible_country_codes": [ - "TH" - ], - "username": "HoneKrasae", - "user_id": "1240684293719904256", - "monetization_restricted": true, - "content_category_ids": [ - "sr" - ] - }, - { - "monetizable_country_codes": [ - "US" - ], - "promotion_eligible_country_codes": [ - "US" - ], - "username": "Sportskind", - "user_id": "1232708694418300930", - "monetization_restricted": true, - "content_category_ids": [ - "se" - ] - }, - { - "monetizable_country_codes": [ - "IN", - "KW", - "ID", - "EG", - "SG", - "TH", - "MY", - "PH", - "ES", - "US", - "AU", - "SA", - "AE", - "LB", - "GB", - "FR", - "KR", - "BR", - "MX", - "QA", - "CA", - "JP" - ], - "promotion_eligible_country_codes": [ - "KW", - "EG", - "SA", - "AE", - "LB", - "QA" - ], - "username": "almeerathShow", - "user_id": "1229410512762437633", - "monetization_restricted": false, - "content_category_ids": [ - "sh" - ] - }, - { - "monetizable_country_codes": [ - "US" - ], - "promotion_eligible_country_codes": [ - "US" - ], - "username": "SeeYourVoiceFOX", - "user_id": "1225490734653947904", - "monetization_restricted": true, - "content_category_ids": [ - "sh" - ] - }, - { - "monetizable_country_codes": [ - "IN", - "KW", - "ID", - "EG", - "SG", - "TH", - "MY", - "PH", - "ES", - "US", - "AU", - "SA", - "AE", - "LB", - "GB", - "FR", - "KR", - "BR", - "MX", - "QA", - "CA", - "JP" - ], - "promotion_eligible_country_codes": [ - "US" - ], - "username": "AUProSports", - "user_id": "1219303449768185859", - "monetization_restricted": false, - "content_category_ids": [ - "se" - ] - } - ] - } -``` -### Recommendations - - -#### GET accounts/:account_id/recommendations[](#get-accounts-account-id-recommendations "Permalink to this headline") - -Status: _Closed Beta_ - -Retrieve campaign recommendations associated with this ads account. Currently there is a limit of 1 recommendation per funding instrument. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/5/accounts/:account_id/recommendations` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - "request": { - "params": { - "account_id": "18ce54d4x5t" - } - }, - "total_count": 1, - "data": [ - { - "funding_instrument_id": "gpvzb", - "id": "62ce8zza1q0w", - "account_id": "18ce54d4x5t", - "status": "PENDING", - "message": "Recommendation for testing", - "created_at": "2016-11-14T23:07:54Z", - "updated_at": "2016-11-14T23:07:54Z" - } - ] -``` - -#### GET accounts/:account\_id/recommendations/:recommendation\_id[](#get-accounts-account-id-recommendations-recommendation-id "Permalink to this headline") - -Status: _Closed Beta_ - -Retrieve a specific campaign recommendation associated with this ads account. - -The campaign recommendation contains a full set of changes suggested for the campaign structure represented as an object tree. The response tree is intended to work in conjunction with the Batch API endpoints, but it can also be mapped to single update endpoints as appropriate (Create for POST, Update for PUT, Delete for DELETE). - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| recommendation_id
_required_ | A reference to the recommendation ID you are operating within the request

Type: string

Example: `62ce8zza1q0w` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "recommendation_id": "62ce8zza1q0w", - "account_id": "18ce54d4x5t" - } - }, - "data_type": "recommendations", - "data": { - "changes": [ - { - "entity_type": "campaigns", - "params": { - "start_time": "2016-11-08T22:00:00Z", - "daily_budget_amount_local_micro": 2200000, - "end_time": "2016-11-16T07:59:00Z", - "total_budget_amount_local_micro": 12000000, - "id": "64m0d" - }, - "operation_type": "Update", - "dependent_entities": [ - { - "entity_type": "line_items", - "params": { - "name": "Campaign for recommendations", - "placements": [ - "TWITTER_TIMELINE" - ], - "bid_amount_local_micro": 1430000, - "id": "6f5kq", - "include_sentiment": "ALL" - }, - "operation_type": "Update", - "dependent_entities": [ - { - "entity_type": "targeting_criteria", - "params": { - "id": "a8po6p" - }, - "operation_type": null, - "dependent_entities": [] - }, - { - "entity_type": "targeting_criteria", - "params": { - "line_item_id": "6f5kq", - "name": "election results", - "targeting_value": "election results", - "targeting_type": "PHRASE_KEYWORD" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "promoted_tweets", - "params": { - "id": "101ftp" - }, - "operation_type": "Delete", - "dependent_entities": [] - }, - { - "entity_type": "targeting_criteria", - "params": { - "line_item_id": "6f5kq", - "name": "Male", - "targeting_value": 1, - "targeting_type": "GENDER" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "targeting_criteria", - "params": { - "line_item_id": "6f5kq", - "name": "San Francisco-Oakland-San Jose CA, US", - "targeting_value": "", - "targeting_type": "LOCATION" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "promoted_tweets", - "params": { - "id": "101fto" - }, - "operation_type": "Delete", - "dependent_entities": [] - }, - { - "entity_type": "promoted_tweets", - "params": { - "line_item_id": "6f5kq", - "display_properties": [], - "paused": false, - "approval_status": "ACCEPTED", - "tweet_id": "91125952589766656" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "targeting_criteria", - "params": { - "line_item_id": "6f5kq", - "name": "Partner audience targeting", - "targeting_value": "v2cx", - "targeting_type": "NEGATIVE_BEHAVIOR" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "targeting_criteria", - "params": { - "line_item_id": "6f5kq", - "name": "AGE_21_TO_34", - "targeting_value": "AGE_21_TO_34", - "targeting_type": "AGE" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "targeting_criteria", - "params": { - "id": "a8po6o" - }, - "operation_type": "Delete", - "dependent_entities": [] - }, - { - "entity_type": "promoted_tweets", - "params": { - "line_item_id": "6f5kq", - "display_properties": [], - "paused": false, - "approval_status": "ACCEPTED", - "tweet_id": "991101965843460096" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "promoted_tweets", - "params": { - "line_item_id": "6f5kq", - "display_properties": [], - "paused": false, - "approval_status": "ACCEPTED", - "tweet_id": "991127212156096516" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "targeting_criteria", - "params": { - "line_item_id": "6f5kq", - "name": "debate", - "targeting_value": "debate", - "targeting_type": "NEGATIVE_PHRASE_KEYWORD" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "targeting_criteria", - "params": { - "line_item_id": "6f5kq", - "name": "60004, IL, US", - "targeting_value": "", - "targeting_type": "LOCATION" - }, - "operation_type": "Create", - "dependent_entities": [] - }, - { - "entity_type": "targeting_criteria", - "params": { - "id": "a8po6n" - }, - "operation_type": null, - "dependent_entities": [] - }, - { - "entity_type": "promoted_tweets", - "params": { - "id": "101ftn" - }, - "operation_type": null, - "dependent_entities": [] - } - ] - } - ] - } - ], - "funding_instrument_id": "gpvzb", - "id": "62ce8zza1q0w", - "account_id": "18ce54d4x5t", - "status": "PENDING", - "message": "Recommendation for testing", - "created_at": "2016-11-14T23:07:54Z", - "updated_at": "2016-11-14T23:07:54Z" - } - } -``` -### Scheduled Promoted Tweets - - -#### GET accounts/:account\_id/scheduled\_promoted_tweets[](#get-accounts-account-id-scheduled-promoted-tweets "Permalink to this headline") - -Retrieve details for some or all scheduled promoted Tweets associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| line\_item\_ids
_optional_ | Scope the response to just the scheduled Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8xdpe` | -| scheduled\_promoted\_tweet_ids
_optional_ | Scope the response to just the desired scheduled promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `1xboq` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "scheduled_promoted_tweet_ids": [ - "1xboq" - ], - "account_id": "18ce54d4x5t" - } - }, - "next_cursor": null, - "data": [ - { - "line_item_id": "8xdpe", - "id": "1xboq", - "created_at": "2017-06-01T19:53:32Z", - "updated_at": "2017-06-01T20:00:06Z", - "scheduled_tweet_id": "870366669373194240", - "tweet_id": "870369382207070208", - "deleted": false - } - ] - } -``` - -#### GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id[](#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id "Permalink to this headline") - -Retrieve a specific scheduled promoted Tweet associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| scheduled\_promoted\_tweet_id
_required_ | A reference to the scheduled promoted Tweet you are operating with in the request.

Type: string

Example: `1xboq` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "scheduled_promoted_tweet_id": "1xboq", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "line_item_id": "8xdpe", - "id": "1xboq", - "created_at": "2017-06-01T19:53:32Z", - "updated_at": "2017-06-01T20:00:06Z", - "scheduled_tweet_id": "870366669373194240", - "tweet_id": "870369382207070208", - "deleted": false - } - } -``` - -#### POST accounts/:account\_id/scheduled\_promoted_tweets[](#post-accounts-account-id-scheduled-promoted-tweets "Permalink to this headline") - -Associate a scheduled Tweet with the specified line item. - -**Note**: It is not possible to update (PUT) scheduled promoted Tweet entities. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8xdpe` | -| scheduled\_tweet\_id
_required_ | A reference to the scheduled Tweet you are operating with in the request.

Type: long

Example: `870358555227860992` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "line_item_id": "8xdpe", - "id": "1xtfl", - "created_at": "2017-06-08T07:25:26Z", - "updated_at": "2017-06-08T07:25:26Z", - "scheduled_tweet_id": "870358555227860992", - "tweet_id": null, - "deleted": false - }, - "request": { - "params": { - "line_item_id": "8xdpe", - "scheduled_tweet_id": 870358555227860992, - "account_id": "18ce54d4x5t" - } - } - } -``` - -#### DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id[](#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id "Permalink to this headline") - -Disassociate a scheduled Tweet from the specified line item. - -**Note**: `scheduled_promoted_tweets` can only be deleted _before_ the scheduled Tweet's `scheduled_at` time. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| scheduled\_promoted\_tweet_id
_required_ | A reference to the scheduled promoted Tweet you are operating with in the request. This is the `id` attribute from a [GET accounts/:account\_id/scheduled\_promoted_tweets](#get-accounts-account-id-scheduled-promoted-tweets) response object.

Type: string

Example: `1xtfl` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "line_item_id": "8xdpe", - "id": "1xtfl", - "created_at": "2017-06-08T07:25:26Z", - "updated_at": "2017-06-15T05:14:12Z", - "scheduled_tweet_id": "870358555227860992", - "tweet_id": null, - "deleted": true - }, - "request": { - "params": { - "scheduled_promoted_tweet_id": "1xtfl", - "account_id": "18ce54d4x5t" - } - } - } -``` -### Targeting Criteria - - -#### GET accounts/:account\_id/targeting\_criteria[](#get-accounts-account-id-targeting-criteria "Permalink to this headline") - -Retrieve details for some or all of the targeting criteria associated with line items under the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/targeting_criteria` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_ids
_required_ | Scope the response to just the targeting criteria under the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8u94t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| lang
_optional_ | An [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional `localized_name` attribute will be returned in the response for objects where a localized name is available.

Type: string

Example: `fr` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.

Type: string

Example: `created_at-asc` | -| targeting\_criterion\_ids
_optional_ | Scope the response to just the desired targeting criteria by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `dpl3a6` | -| 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "line_item_ids": [ - "8u94t" - ] - } - }, - "next_cursor": null, - "data": [ - { - "line_item_id": "8u94t", - "name": "Custom audience targeting", - "id": "dpl3a6", - "operator_type": "EQ", - "created_at": "2017-05-26T03:29:35Z", - "targeting_value": "249yj", - "updated_at": "2017-05-26T03:29:35Z", - "deleted": false, - "targeting_type": "CUSTOM_AUDIENCE" - } - ] - } -``` - -#### GET accounts/:account\_id/targeting\_criteria/:targeting\_criterion\_id[](#get-accounts-account-id-targeting-criteria-targeting-criterion-id "Permalink to this headline") - -Retrieve a specific targeting criterion associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| targeting\_criterion\_id
_required_ | A reference to the targeting criterion you are operating with in the request.

Type: string

Example: `eijd4y` | -| lang
_optional_ | An [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional `localized_name` attribute will be returned in the response for objects where a localized name is available.

Type: string

Example: `fr` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "targeting_criterion_id": "eijd4y", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "line_item_id": "619jl", - "name": "🤖", - "id": "eijd4y", - "created_at": "2017-07-06T16:51:04Z", - "targeting_value": "🤖", - "updated_at": "2017-07-06T16:51:04Z", - "deleted": false, - "targeting_type": "BROAD_KEYWORD" - } - } -``` - -#### POST accounts/:account\_id/targeting\_criteria[](#post-accounts-account-id-targeting-criteria "Permalink to this headline") - -See the [Targeting Options](/x-ads-api/campaign-management#targeting-options) page to find `targeting_value`s for specific targeting types. We recommend that you refresh all data weekly, to ensure that you are working with the latest set of targeting type values. We change values and available targeting criteria from time to time; while the majority of these don't change often, some do. There is no guarantee that these values will not change. - -Use the `BROAD_KEYWORD`, `EXACT_KEYWORD`, `PHRASE_KEYWORD`, or `UNORDERED_KEYWORD` targeting types with the keywords specified in the `targeting_value`. Exclude keywords by using the `operator_type` request parameter set to `NE`. See [targeting keyword types](/x-ads-api/campaign-management#targeting) for a detailed description of each type. - -**Note**: It is only possible to target a single age bucket per line item. - -**Note**: To target a Custom Audience, that audience must be targetable. i.e., `targerable` _must_ equal `true`. - -**Note**: When using targeting type `TV_SHOW`, there must be at least one `LOCATION` targeting criterion on the line item prior to setting the `TV_SHOW` targeting and all `LOCATION` must be within the same locale as the `TV_SHOW` being targeted. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/targeting_criteria` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `69ob` | -| operator_type
_required_ | Specify the relationship that the targeting criterion should have. For example, to exclude keywords, use `operator_type=NE`.

Type: enum

Possible values: `EQ`, `NE`, `GTE`, `LT` | -| targeting_type
_required_ | The type of targeting that will be applied to this line item.

Possible non-keyword-based values include: `AGE`, `DEVICE`, `EVENT`, `CAMPAIGN_ENGAGEMENT`, `CAMPAIGN_ENGAGEMENT_LOOKALIKE`, `CONVERSATION`, `ENGAGEMENT_TYPE`, `FOLLOWERS_OF_USER`, `GENDER`, `INTEREST`, `LANGUAGE`, `LIVE_TV_EVENT`, `LOCATION`, `NETWORK_ACTIVATION_DURATION`, `NETWORK_OPERATOR`, `PLATFORM`, `PLATFORM_VERSION`, `SIMILAR_TO_FOLLOWERS_OF_USER`, `TV_SHOW`, `USER_ENGAGEMENT`, `USER_ENGAGEMENT_LOOKALIKE`, `WIFI_ONLY`

**Note**: It is only possible to target a single `AGE` bucket per line item.

Possible keyword-based values include: `BROAD_KEYWORD`, `EXACT_KEYWORD`, `PHRASE_KEYWORD`, `UNORDERED_KEYWORD`

Possible custom audience values include: `CUSTOM_AUDIENCE`, `CUSTOM_AUDIENCE_EXPANDED`

Possible installed app store category values: `APP_STORE_CATEGORY`, `APP_STORE_CATEGORY_LOOKALIKE`

Possible Twitter Audience Platform (TAP) app exclusion: `APP_LIST` (may only be used with `operator_type=NE`) | -| targeting_value
_required_ | Specify which user, which interest, which location, which event, which platform, which platform version, which device, which keyword or phrase, which gender, which custom audience, which app store category, or which exclusion of an app list this targeting will be applied to, depending on the selected targeting_type.

Type: string

Example: `174958347` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "line_item_id": "619jl", - "name": "technology", - "id": "fbyjlr", - "created_at": "2017-09-06T07:31:21Z", - "targeting_value": "technology", - "updated_at": "2017-09-06T07:31:21Z", - "deleted": false, - "targeting_type": "BROAD_KEYWORD" - }, - "request": { - "params": { - "line_item_id": "619jl", - "targeting_type": "BROAD_KEYWORD", - "targeting_value": "technology", - "account_id": "18ce54d4x5t" - } - } - } -``` - -#### POST batch/accounts/:account\_id/targeting\_criteria[](#post-batch-accounts-account-id-targeting-criteria "Permalink to this headline") - -Allows the batch creation of new Targeting Criteria with a single request. - -**Batch Requests** - -* The current maximum batch size is 500. -* 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 Targeting Criteria parameter) are shown in the response under the `operation_errors` object. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/batch/accounts/:account_id/targeting_criteria` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| operation_type
_required_ | The per item operation type being performed.

Type: enum

Possible values: `Create`, `Delete` | -| params
_required_ | A JSON object containing all the parameters for the targeting criteria objects. For a list of required and optional targeting criteria parameters, see [here](#post-accounts-account-id-targeting-criteria).

In addition, this endpoint supports an `operator_type` parameter that works in conjunction with certain `targeting_type` values. The possible values for this parameter are `EQ` for equal to, `GTE` for greater than or equal to, `LT` for less than, and `NE` for not equal to. | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/targeting_criteria` - -```json - [ - { - "operation_type":"Create", - "params":{ - "line_item_id":"6f9an", - "targeting_type":"LOCATION", - "targeting_value":"5122804691e5fecc" - } - }, - { - "operation_type":"Delete", - "params":{ - "targeting_criterion_id":"al2rua" - } - } - ] -``` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data_type": "targeting_criterion", - "data": [ - { - "line_item_id": "6f9an", - "name": "San Francisco-Oakland-San Jose CA, US", - "id": "al7vt2", - "location_type": "CITY", - "operator_type": "EQ", - "created_at": "2016-11-11T22:59:50Z", - "targeting_value": "5122804691e5fecc", - "updated_at": "2016-11-11T22:59:50Z", - "deleted": false, - "targeting_type": "LOCATION" - }, - { - "line_item_id": "6keuo", - "name": "accounts", - "id": "al2rua", - "operator_type": "EQ", - "created_at": "2016-11-11T17:50:19Z", - "targeting_value": "accounts", - "updated_at": "2016-11-11T22:59:50Z", - "deleted": true, - "targeting_type": "BROAD_KEYWORD" - } - ], - "request": [ - { - "params": { - "line_item_id": "6f9an", - "targeting_type": "LOCATION", - "targeting_value": "5122804691e5fecc", - "account_id": "18ce54d4x5t" - }, - "operation_type": "Create" - }, - { - "params": { - "targeting_criterion_id": "al2rua", - "account_id": "18ce54d4x5t" - }, - "operation_type": "Delete" - } - ] - } -``` - -#### DELETE accounts/:account\_id/targeting\_criteria/:targeting\_criterion\_id[](#delete-accounts-account-id-targeting-criteria-targeting-criterion-id "Permalink to this headline") - -Delete the specified targeting criterion belonging to the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| targeting\_criterion\_id
_required_ | A reference to the targeting criterion you are operating with in the request.

Type: string

Example: `dpl3a6` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": { - "line_item_id": "8u94t", - "name": "Custom audience targeting", - "id": "dpl3a6", - "created_at": "2017-05-26T03:29:35Z", - "targeting_value": "249yj", - "updated_at": "2017-08-30T18:38:58Z", - "deleted": true, - "targeting_type": "CUSTOM_AUDIENCE" - }, - "request": { - "params": { - "targeting_criterion_id": "dpl3a6", - "account_id": "18ce54d4x5t" - } - } - } -``` -### Targeting Options - - -* [App Store Categories](#get-targeting-criteria-app-store-categories) -* [Conversation](#get-targeting-criteria-conversations) -* [Devices](#get-targeting-criteria-devices) -* [Events](#get-targeting-criteria-events) -* [Interests](#get-targeting-criteria-interests) -* [Languages](#get-targeting-criteria-languages) -* [Locations](#get-targeting-criteria-locations) -* [Network Operators](#get-targeting-criteria-network-operators) -* [Platform Versions](#get-targeting-criteria-platform-versions) -* [Platforms](#get-targeting-criteria-platforms) -* [TV Markets](#get-targeting-criteria-tv-markets) -* [TV Shows](#get-targeting-criteria-tv-shows) - -#### GET targeting\_criteria/app\_store_categories[](#get-targeting-criteria-app-store-categories "Permalink to this headline") - -Discover available app store category-based targeting criteria for Promoted Products. App store categories are available for the iOS App Store and the Google Play store only. - -Installed app category targeting allows targeting of users based on the categories of apps they have installed or have indicated interest in. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/app_store_categories` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| q
_optional_ | An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: `music` | -| os_type
_optional_ | Scope the results by a specific app store.

Type: enum

Possible values: `ANDROID`, `IOS` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "name": "Games: Music", - "targeting_type": "APP_STORE_CATEGORY", - "targeting_value": "qouq", - "os_type": "IOS" - }, - { - "name": "Music", - "targeting_type": "APP_STORE_CATEGORY", - "targeting_value": "qov2", - "os_type": "IOS" - } - ], - "request": { - "params": { - "q": "music", - "os_type": "IOS" - } - } - } -``` - -#### GET targeting_criteria/conversations[](#get-targeting-criteria-conversations "Permalink to this headline") - -Discover available conversation-based targeting criteria for Promoted Products. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/conversations` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| conversation_type
_optional_ | An optional query to scope to a certain conversation type.

Type: enum

Possible values: `ACTORS`, `ATHLETES`, `BOOK_GENRES`, `BOOKS`, `BRAND_CATEGORIES`, `BRANDS`, `CELEBRITIES`, `COACHES`, `DIGITAL_CREATORS`, `ENTERTAINMENT_BRANDS`, `ENTERTAINMENT_PERSONALITIES`, `FICTIONAL_CHARACTERS`, `JOURNALISTS`, `LIFESTYLES`, `MOVIE_GENRES`, `MOVIES`, `MUSIC_GENRES`, `MUSICIANS`, `NEWS_STORIES`, `NEWS`, `PERSONS`, `PLACES`, `PODCASTS`, `POLITICAL_AFFILIATIONS`, `POLITICIANS`, `PRODUCTS`, `RADIO_STATIONS`, `SPORTS_LEAGUES`, `SPORTS_PERSONALITIES`, `SPORTS_TEAMS`, `SPORTS`, `TRENDS`, `TV_SHOWS`, `VIDEO_GAME_PLATFORMS`, `VIDEO_GAME_PUBLISHERS`, `VIDEO_GAMES` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "count": 2 - } - }, - "next_cursor": "1f7m7", - "data": [ - { - "targeting_type": "CONVERSATION", - "targeting_value": "a1", - "name": "NFL", - "conversation_type": "SPORTS" - }, - { - "targeting_type": "CONVERSATION", - "targeting_value": "a2", - "name": "NBA", - "conversation_type": "SPORTS" - } - ] - } -``` - -#### GET targeting_criteria/devices[](#get-targeting-criteria-devices "Permalink to this headline") - -Discover available device-based targeting criteria for Promoted Products. Device targeting is available for Promoted Tweets. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/devices` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | -| q
_optional_ | An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: `apple` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "name": "iPhone 3GS", - "manufacturer": "Apple", - "os_type": "iOS", - "targeting_value": "1q", - "targeting_type": "DEVICE" - }, - { - "name": "iPhone 4", - "manufacturer": "Apple", - "os_type": "iOS", - "targeting_value": "1r", - "targeting_type": "DEVICE" - } - ], - "request": { - "params": { - "q": "iphone", - "count": 2 - } - } - } -``` - -#### GET targeting_criteria/events[](#get-targeting-criteria-events "Permalink to this headline") - -Discover available event-based targeting criteria for Promoted Products. Only one event can be targeted per line item. - -**Note**: Events often exist across timezones, leading to complications when considering event times from cross-timezone perspectives. To simplify this, all event `start_time` and `end_time` values on this endpoint are represented in UTC±00:00, irrespective of the event's locale and timezone. This design should be kept in mind when querying and interacting with event `start_time` and `end_time` values. For example, Independence Day for the US is represented as `start_time=2017-07-04T00:00:00Z` and `end_time=2017-07-05T00:00:00Z` in UTC±00:00, and thus avoids the issue of this holiday existing across multiple timezones within the US. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/events` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| event_types
_required_ | An optional query to scope to certain event types.

Type: enum

Possible values: `CONFERENCE`, `HOLIDAY`, `MUSIC_AND_ENTERTAINMENT`, `OTHER`, `POLITICS`, `RECURRING`, `SPORTS` | -| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | -| country_codes
_optional_ | An optional query to scope a targeting criteria search to particular countries with the 2 letter ISO country code. If this parameter is not specified, all events are returned.

Type: string | -| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| end_time
_optional_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the campaign will end.

Type: string

Example: `2017-10-05T00:00:00Z` | -| start_time
_optional_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.

**Note**: Defaults to the current time.

Type: string

Example: `2017-07-05T00:00:00Z` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/events?count=1` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "count": 1 - } - }, - "data_type": "events", - "data": [ - { - "reach": { - "total_reach": null - }, - "name": "New Year's", - "start_time": "2017-12-31T00:00:00Z", - "top_users": [], - "top_tweets": [], - "top_hashtags": [], - "gender_breakdown_percentage": {}, - "end_time": "2018-01-02T00:00:00Z", - "country_code": null, - "device_breakdown_percentage": {}, - "targeting_value": "1ex", - "is_global": true, - "event_type": "HOLIDAY", - "country_breakdown_percentage": {} - } - ], - "next_cursor": "uww0" - } -``` - -#### GET targeting_criteria/interests[](#get-targeting-criteria-interests "Permalink to this headline") - -Discover available interest-based targeting criteria for Promoted Products. Interests change infrequently, however we suggest you refresh this list at least once weekly. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/interests` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| q
_optional_ | An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: `books` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/interests?q=books` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "name": "Books and literature/Biographies and memoirs", - "targeting_type": "INTEREST", - "targeting_value": "1001" - } - ], - "request": { - "params": { - "q": "books", - "count": 1 - } - }, - "next_cursor": "6by4n4" - } -``` - -#### GET targeting_criteria/languages[](#get-targeting-criteria-languages "Permalink to this headline") - -Discover languages available for targeting. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/languages` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| q
_optional_ | An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: `english` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/languages?q=english` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "name": "English", - "targeting_type": "LANGUAGE", - "targeting_value": "en" - } - ], - "request": { - "params": { - "q": "english" - } - }, - "next_cursor": null - } -``` - -#### GET targeting_criteria/locations[](#get-targeting-criteria-locations "Permalink to this headline") - -Discover available location-based targeting criteria for Promoted Products. Geo-targeting is available for Promoted Accounts and Promoted Tweets at the country level, state/region level, city level, and postal code level. Postal code targeting must be used if you wish to retrieve analytics at the postal code level. - -**Note**: To retrieve specific targetable cities, such as San Francisco or New York, use the `CITIES` enum with the `location_type` request parameter. - -To target Designated Market Areas (DMAs), use the `METROS` enum. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/locations` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | -| country_code
_optional_ | An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. Omit this parameter to retrieve results for all countries.

Type: string

Example: `JP` | -| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| location_type
_optional_ | Scope the results by a specific kind of location. More granular targeting than `COUNTRIES` may not be available in all locations.

Type: enum

Possible values: `COUNTRIES`, `REGIONS`, `METROS`, `CITIES`, `POSTAL_CODES` | -| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.

Type: string

Example: `New York` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "name": "Los Angeles, Los Angeles CA, CA, USA", - "country_code": "US", - "location_type": "CITIES", - "targeting_value": "3b77caf94bfc81fe", - "targeting_type": "LOCATION" - }, - { - "name": "East Los Angeles, Los Angeles CA, CA, USA", - "country_code": "US", - "location_type": "CITIES", - "targeting_value": "67571a7baaa5906b", - "targeting_type": "LOCATION" - }, - { - "name": "Lake Los Angeles, Los Angeles CA, CA, USA", - "country_code": "US", - "location_type": "CITIES", - "targeting_value": "ea9bfbd43c93400f", - "targeting_type": "LOCATION" - }, - { - "name": "Los Gatos, San Francisco-Oakland-San Jose CA, CA, USA", - "country_code": "US", - "location_type": "CITIES", - "targeting_value": "a2de7c70b82b0ca0", - "targeting_type": "LOCATION" - }, - { - "name": "Los Altos, Monterey-Salinas CA, CA, USA", - "country_code": "US", - "location_type": "CITIES", - "targeting_value": "6a4364ea6f987c10", - "targeting_type": "LOCATION" - }, - { - "name": "Los Banos, CA, USA", - "country_code": "US", - "location_type": "CITIES", - "targeting_value": "b1b6fc646de75904", - "targeting_type": "LOCATION" - }, - { - "name": "Los Alamitos, Los Angeles CA, CA, USA", - "country_code": "US", - "location_type": "CITIES", - "targeting_value": "0799ff0a3c1006e9", - "targeting_type": "LOCATION" - }, - { - "name": "Los Angeles, US", - "country_code": "US", - "location_type": "CITIES", - "targeting_value": "019940ae78c7b3bc", - "targeting_type": "LOCATION" - } - ], - "request": { - "params": { - "location_type": "CITIES", - "q": "los angeles" - } - }, - "next_cursor": null - } -``` - -#### GET targeting\_criteria/network\_operators[](#get-targeting-criteria-network-operators "Permalink to this headline") - -Discover available network operator-based targeting criteria for Promoted Products. - -This endpoint enables you to lookup targetingable carriers, such as AT&T, Verizon, Sprint, T-Mobile, etc., in multiple countries. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/network_operators` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | -| country_code
_optional_ | An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned.

Type: string

Default: `US` | -| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: `Airpeak` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "country_code": "US", - "targeting_type": "NETWORK_OPERATOR", - "name": "Advantage", - "targeting_value": "2l" - }, - { - "country_code": "US", - "targeting_type": "NETWORK_OPERATOR", - "name": "Aeris", - "targeting_value": "1b" - }, - { - "country_code": "US", - "targeting_type": "NETWORK_OPERATOR", - "name": "Airadigm", - "targeting_value": "2t" - }, - { - "country_code": "US", - "targeting_type": "NETWORK_OPERATOR", - "name": "Airlink PCS", - "targeting_value": "14" - }, - { - "country_code": "US", - "targeting_type": "NETWORK_OPERATOR", - "name": "Airpeak", - "targeting_value": "1i" - } - ], - "request": { - "params": { - "country_code": "US", - "count": 5 - } - }, - "next_cursor": "o7x9iet1a5u608olj4" - } -``` - -#### GET targeting\_criteria/platform\_versions[](#get-targeting-criteria-platform-versions "Permalink to this headline") - -Discover available mobile OS version-based targeting criteria for Promoted Products. Platform version targeting is available for Promoted Accounts and Promoted Tweets. This allows targeting down to the point release of a mobile operating system version, such as Android 8.0 or iOS 10.0. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/platform_versions` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: `jelly bean` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/platform_versions` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - {...}, - { - "name": "Ice Cream Sandwich", - "number": "4.0", - "os_type": "Android", - "targeting_type": "PLATFORM_VERSION", - "targeting_value": "17" - }, - { - "name": "Jelly Bean", - "number": "4.1", - "os_type": "Android", - "targeting_type": "PLATFORM_VERSION", - "targeting_value": "18" - }, - {...} - ], - "data_type": "targeting_criterion", - "request": { - "params": {} - } - } -``` - -#### GET targeting_criteria/platforms[](#get-targeting-criteria-platforms "Permalink to this headline") - -Discover available platform-based targeting criteria for Promoted Products. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/platforms` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | -| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: `ios`, `blackberry` | -| lang
_optional_ | Using a [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional localized_name attribute will be returned in the response.

Type: int, string

Example: `fr` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/platforms` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "name": "iOS", - "targeting_type": "PLATFORM", - "targeting_value": "0" - }, - { - "name": "Android", - "targeting_type": "PLATFORM", - "targeting_value": "1" - }, - { - "name": "BlackBerry phones and tablets", - "targeting_type": "PLATFORM", - "targeting_value": "2" - }, - { - "name": "Mobile web on other devices", - "targeting_type": "PLATFORM", - "targeting_value": "3" - }, - { - "name": "Desktop and laptop computers", - "targeting_type": "PLATFORM", - "targeting_value": "4" - } - ], - "request": { - "params": {} - } - } -``` - -#### GET targeting\_criteria/tv\_markets[](#get-targeting-criteria-tv-markets "Permalink to this headline") - -Discover available TV markets where TV shows can be targeted. Returns markets by locale that can used to query the [GET targeting\_criteria/tv\_shows](/x-ads-api/campaign-management#get-targeting-criteria-tv-shows) endpoint. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/tv_markets` - -**Parameters[](#parameters "Permalink to this headline")** - -None - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/tv_markets` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "data": [ - { - "name": "France", - "country_code": "FR", - "locale": "fr-FR" - }, - { - "name": "Chile", - "country_code": "CL", - "locale": "es-CL" - }, - { - "name": "Germany", - "country_code": "DE", - "locale": "de-DE" - }, - { - "name": "Netherlands", - "country_code": "NL", - "locale": "nl-NL" - }, - { - "name": "United States", - "country_code": "US", - "locale": "en-US" - }, - { - "name": "Venezuela", - "country_code": "VE", - "locale": "es-VE" - }, - { - "name": "Brazil", - "country_code": "BR", - "locale": "pt-BR" - }, - { - "name": "Mexico", - "country_code": "MX", - "locale": "es-MX" - }, - { - "name": "Colombia", - "country_code": "CO", - "locale": "es-CO" - }, - { - "name": "United Kingdom", - "country_code": "GB", - "locale": "en-GB" - }, - { - "name": "Argentina", - "country_code": "AR", - "locale": "es-AR" - }, - { - "name": "Japan", - "country_code": "JP", - "locale": "ja-JP" - }, - { - "name": "Canada", - "country_code": "CA", - "locale": "en-CA" - }, - { - "name": "Spain", - "country_code": "ES", - "locale": "es-ES" - }, - { - "name": "Italy", - "country_code": "IT", - "locale": "it-IT" - }, - { - "name": "United States - Hispanic", - "country_code": "US", - "locale": "es-US" - }, - { - "name": "Ireland", - "country_code": "IE", - "locale": "en-IE" - } - ], - "request": { - "params": {} - } - } -``` - -#### GET targeting\_criteria/tv\_shows[](#get-targeting-criteria-tv-shows "Permalink to this headline") - -Discover available TV show-based targeting criteria for Promoted Products. TV show targeting is available for Promoted Tweets in certain markets. See the [GET targeting\_criteria/tv\_markets](/x-ads-api/campaign-management#get-targeting-criteria-tv-markets) endpoint for available markets. - -**Note**: Any audience that contains fewer than 1,000 users will appear with an `estimated_users` value of `1000`. - -**Note**: TV channel and genre targeting options are no longer supported. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/targeting_criteria/tv_shows` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| locale
_required_ | A required parameter that specifies the tv\_market\_locale to query for available TV shows. TV markets are queried based on `locale` returned from the [GET targeting\_criteria/tv\_markets](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria).

Type: string

Example: `en-US` | -| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `50`
Min, Max: `1`, `50` | -| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: `ios`, `blackberry` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1` - -**Example Response[](#example-response "Permalink to this headline")** - -```jdon - { - "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" - } - } - } -``` -### Targeting Suggestions - - -#### GET accounts/:account\_id/targeting\_suggestions[](#get-accounts-account-id-targeting-suggestions "Permalink to this headline") - -Get up to 50 keyword or user targeting suggestions to complement your initial selection. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/targeting_suggestions` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticating user.

Type: string

Example: `18ce54d4x5t` | -| suggestion_type
_required_ | Specify the type of suggestions to return.

Type: enum

Possible values: `KEYWORD`, `USER_ID` | -| targeting_values
_required_ | Comma separated collection of either keywords or user IDs used to seed the suggestions.

**Note**: These two types of suggestions cannot be mixed.

Example: `756201191646691328` | -| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `30`
Min, Max: `1`, `50` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"` - -**Example Response[](#example-response "Permalink to this headline")** - -```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" - } - } - } -``` -### Tax Settings - - -#### GET accounts/:account\_id/tax\_settings[](#get-accounts-account-id-tax-settings "Permalink to this headline") - -Retrieve tax setting details associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/tax_settings` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t" - } - }, - "data": { - "tax_id": "GB896391250", - "address_city": "London", - "business_relationship": "SELF", - "address_street1": "21 March St", - "address_last_name": null, - "address_company": "ABC, Inc.", - "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 - } - } -``` - -#### PUT accounts/:account\_id/tax\_settings[](#put-accounts-account-id-tax-settings "Permalink to this headline") - -Update the tax settings for the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/tax_settings` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| address_city
_optional_ | The city for the account owner's address.

Type: string

Example: `San Francisco` | -| address_country
_optional_ | The two-letter country code for the account owner's address.

Type: string

Example: `US` | -| address_email
_optional_ | The email associated with the account owner's address.

Type: string

Example: `api@mctestface.com` | -| address\_first\_name
_optional_ | The first name for the account owner's address.

Type: string

Example: `API` | -| address\_last\_name
_optional_ | The last name for the account owner's address.

Type: string

Example: `McTestface` | -| address_name
_optional_ | The company name for the account owner's address.

Type: string

Example: `ABC, Co.` | -| address\_postal\_code
_optional_ | The postal code for the account owner's address.

Type: string

Example: `94102` | -| address_region
_optional_ | The region for the account owner's address.

Type: string

Example: `California` | -| address_street1
_optional_ | The street line for the account owner's address.

Type: string

Example: `21 March St` | -| address_street2
_optional_ | The second street line for the account owner's address.

Type: string

Example: `Suite 99` | -| bill_to
_optional_ | The entity that is billed.

Type: enum

Possible values: `ADVERTISER`, `AGENCY` | -| business_relationship
_optional_ | Whether the account is owned by the advertiser or by the agency.

Type: enum

Possible values: `AGENCY`, `SELF` | -| client\_address\_city
_optional_ | The city for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Toronto` | -| client\_address\_country
_optional_ | The two-letter country code for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `CA` | -| client\_address\_email
_optional_ | The email associated with the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `ads@brand.com` | -| client\_address\_first_name
_optional_ | The first name for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Brand` | -| client\_address\_last_name
_optional_ | The last name for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Advertiser` | -| client\_address\_name
_optional_ | The company name for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Brand, Inc.` | -| client\_address\_postal_code
_optional_ | The postal code for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `M5H 2N2` | -| client\_address\_region
_optional_ | The region for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Ontario` | -| client\_address\_street1
_optional_ | The street line for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `280 Queen St W` | -| client\_address\_street2
_optional_ | The second street line for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `The 6` | -| invoice_jurisdiction
_optional_ | Invoice jurisdiction.

Type: enum

Possible values: `LOI_SAPIN`, `NONE`, `NOT_SET` | -| tax_category
_optional_ | Whether the taxation should be individual or business.

Type: enum

Possible values: `BUSINESS_NO_VAT`, `BUSINESS_WITH_VAT`, `INDIVIDUAL` | -| tax\_exemption\_id
_optional_ | VAT exemption ID.

Type: sting

Example: `12345` | -| tax_id
_optional_ | VAT registration ID.

Type: string

Possible values: `67890` | - -**Example Request[](#example-request "Permalink to this headline")** - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.` - -**Example Response[](#example-response "Permalink to this headline")** - -```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 - } - } -``` -### Tracking Tags - - -#### GET accounts/:account\_id/tracking\_tags[](#get-accounts-account-id-tracking-tags "Permalink to this headline") - -Retrieve details for some or all tracking tags associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/tracking_tags` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| line\_item\_ids
_optional_ | Scope the response to just the tracking tags associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `96uzp` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.

Type: string

Example: `created_at-asc` | -| tracking\_tag\_ids
_optional_ | Scope the response to just the desired tracking tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `3m82` | -| 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82` - -**Example Response[](#example-response "Permalink to this headline")** - -```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 - } - ] - } -``` - -#### GET accounts/:account\_id/tracking\_tags/:tracking\_tag\_id[](#get-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline") - -Retrieve a specific tracking tag associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| tracking\_tag\_id
_required_ | A reference to the tracking tag you are operating with in the request.

Type: string

Example: `555j` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j` - -**Example Response[](#example-response "Permalink to this headline")** - -```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 - } - } -``` - -#### POST accounts/:account\_id/tracking\_tags[](#post-accounts-account-id-tracking-tags "Permalink to this headline") - -Associate a tracking tag with the specified line item. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/tracking_tags` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | -| tracking\_tag\_type
_required_ | The type of tracking tag.

Type: enum

Possible value: `IMPRESSION_TAG`, `CLICK_TRACKER` | -| tracking\_tag\_url
_required_ | The tracking tag url provided by the tracking partner.

Type: string

Example: `https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?line_item_id=fdwcl&tracking_tag_type=IMPRESSION_TAG&tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "line_item_id": "fdwcl", - "tracking_tag_type": "IMPRESSION_TAG", - "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309", - "account_id": "18ce54d4x5t" - } - }, - "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 - } - } -``` - -#### PUT accounts/:account\_id/tracking\_tags/:tracking\_tag\_id[](#put-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline") - -Associate a tracking tag with the specified line item. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| tracking\_tag\_url
_required_ | The tracking tag url provided by the tracking partner.

Type: string

Example: `https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` | - -**Example Request[](#example-request "Permalink to this headline")** - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/3m82?tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "tracking_tag_id": "3m82", - "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309", - "account_id": "18ce54d4x5t" - } - }, - "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": "2022-01-26T17:04:26Z", - "deleted": false - } - } -``` - -#### DELETE accounts/:account\_id/tracking\_tags/:tracking\_tag\_id[](#delete-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline") - -Disassociate a tracking tag from the specified line item. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| tracking\_tag\_id
_required_ | A reference to the tracking tag you are operating with in the request.

Type: string

Example: `555j` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "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": "2021-08-29T17:12:58Z", - "deleted": true - } - } -``` -### User Settings - - -(https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87) - -#### GET accounts/:account\_id/user\_settings/:user_id[](#get-accounts-account-id-user-settings-user-id "Permalink to this headline") - - -Retrieves user settings. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management#get-accounts).
The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| user_id
_required_ | A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name.

Type: long

Example: `756201191646691328` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "user_id": "756201191646691328" - } - }, - "data": { - "notification_email": "user@domain.com", - "contact_phone": "", - "contact_phone_extension": "" - } - } -``` - -#### PUT accounts/:account\_id/user\_settings/:user_id[](#put-accounts-account-id-user-settings-user-id "Permalink to this headline") - -Updates user settings. Requires user context. Not accessible by account admins. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| account_id
_required_ | The identifier for the leveraged account. Appears within the resource's path and [GET accounts](/x-ads-api/campaign-management#get-accounts).
The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| user_id
_required_ | A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name.

Type: long

Example: `756201191646691328` | -| notification_email
_optional_ | Email to use for account notifications.

Type: string

Example: `user@domain.com` | -| contact_phone
_optional_ | Contact phone number.

Type: string

Example: `202-555-0128` | -| contact\_phone\_extension
_optional_ | Extension for contact `contact_phone`.

Type: string

Example: `1234` | - -**Example Request[](#example-request "Permalink to this headline")** - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='user@domain.com'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"` - -**Example Response[](#example-response "Permalink to this headline")** - -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "user_id": "756201191646691328" - "notification_email": "user@domain.com", - "subscribed_campaign_events": [ - "ACCOUNT_PERFORMANCE", - "PERFORMANCE_IMPROVEMENT" - ] - } - }, - "data": { - "notification_email": "user@domain.com", - "contact_phone": "", - "Contact_phone_extension": "" - } - } -``` diff --git a/x-ads-api/campaign-management/reference.mdx b/x-ads-api/campaign-management/reference.mdx new file mode 100644 index 000000000..736dc829e --- /dev/null +++ b/x-ads-api/campaign-management/reference.mdx @@ -0,0 +1,6314 @@ +--- +title: Campaign Management API Reference +sidebarTitle: API Reference +description: Complete reference for all Campaign Management endpoints in the X Ads API — Accounts, Campaigns, Line Items, Funding Instruments, Targeting Criteria, Placements, Content Categories, and related objects. +keywords: ["campaign management api", "ads api reference", "line items api", "campaigns endpoint", "targeting criteria", "funding instruments", "x ads api"] +--- + +## API Reference + +### Accounts + + +#### GET accounts[](#get-accounts "Permalink to this headline") + +Retrieve details for some or all advertising-enabled accounts the authenticating user has access to. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| account_ids
_optional_ | Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| q
_optional_ | An optional query to scope resource by `name`.

**Note**: This performs case-insensitive prefix matching.

Type: string

Min, Max length: `1`, `255` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/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 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[](#example-request "Permalink to this headline") + +```json +GET https://ads-api.x.com/12/accounts?account_ids=18ce54d4x5t +``` + +**Example Response[](#example-response "Permalink to this headline")** +```json + { + "request": { + "params": { + "account_ids": [ + "18ce54d4x5t" + ] + } + }, + "next_cursor": null, + "data": [ + { + "name": "API McTestface", + "business_name": null, + "timezone": "America/Los_Angeles", + "timezone_switch_at": "2016-07-21T07:00:00Z", + "id": "18ce54d4x5t", + "created_at": "2016-07-21T22:42:09Z", + "updated_at": "2017-07-06T16:51:04Z", + "business_id": null, + "approval_status": "ACCEPTED", + "deleted": false + } + ] + } +``` +#### GET accounts/:account_id[](#get-accounts-account-id "Permalink to this headline") + +Retrieve a specific account that the authenticating user has access to. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t` + +**Example Response[](#example-response "Permalink to this headline")** +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t" + } + }, + "data": { + "name": "API McTestface", + "business_name": null, + "timezone": "America/Los_Angeles", + "timezone_switch_at": "2016-07-21T07:00:00Z", + "id": "18ce54d4x5t", + "created_at": "2016-07-21T22:42:09Z", + "updated_at": "2017-07-06T16:51:04Z", + "industry_type": "TRAVEL", + "business_id": null, + "approval_status": "ACCEPTED", + "deleted": false + } + } +``` +#### POST accounts[](#post-accounts "Permalink to this headline") + + +Note: **SANDBOX ONLY** + +Create an ads account in the sandbox environment. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api-sandbox.x.com/12/accounts` + +**Parameters[](#parameters "Permalink to this headline")** + +None + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api-sandbox.x.com/12/accounts` + +**Example Response[](#example-response "Permalink to this headline")** +```json + { + "request": { + "params": {} + }, + "next_cursor": null, + "data": [ + { + "name": "Sandbox account", + "business_name": null, + "timezone": "America/Los_Angeles", + "timezone_switch_at": null, + "id": "gq12fh", + "created_at": "2016-07-18T23:02:20Z", + "updated_at": "2016-07-18T23:02:20Z", + "business_id": null, + "approval_status": "ACCEPTED", + "deleted": false + } + ] + } +``` +#### PUT accounts/:account_id[](#put-accounts-account-id "Permalink to this headline") + + +Updates the account name and/or industry type. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts).
The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| name
_optional_ | The name of account.

Type: string

Example: `API McTestface` | +| industry_type
_optional_ | Industry that the account is associated with.

Type: string

Possible values: `AGENCY`, `BUSINESS_TO_BUSINESS`, `ONLINE_SERVICES`, `EDUCATION`, `FINANCIAL`, `HEALTH`, `GOVERNMENT`, `MEDIA`, `MOBILE`, `RESTAURANT`, `RETAIL`, `TECHNOLOGY`, `TRAVEL`, `OTHER` | + +**Example Request[](#example-request "Permalink to this headline")** + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY` + +**Example Response[](#example-response "Permalink to this headline")** +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t" + "name"": "API McTestface 2", + "industry_type": "TECHNOLOGY" + } + }, + "data": { + "name": "API McTestface 2", + "business_name": null, + "timezone": "America/Los_Angeles", + "timezone_switch_at": "2016-07-21T07:00:00Z", + "id": "18ce54d4x5t", + "created_at": "2016-07-21T22:42:09Z", + "updated_at": "2017-07-06T16:51:04Z", + "industry_type": "TECHNOLOGY", + "business_id": null, + "approval_status": "ACCEPTED", + "deleted": false + } + } +``` +#### DELETE accounts/:account_id[](#delete-accounts-account-id "Permalink to this headline") + + +Note: **SANDBOX ONLY** + +Delete an ads account in the sandbox environment. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api-sandbox.x.com/12/accounts/:account_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts).

The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh` + +**Example Response[](#example-response "Permalink to this headline")** +```json + { + "data": { + "name": "Sandbox account", + "timezone": "America/Los_Angeles", + "timezone_switch_at": null, + "id": "gq12fh", + "created_at": "2016-07-18T23:02:20Z", + "updated_at": "2017-08-23T18:21:10Z", + "approval_status": "ACCEPTED", + "deleted": true + }, + "request": { + "params": { + "account_id": "gq12fh" + } + } + } +``` +### Account Apps + +[Run in Postman ❯](https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87) + +#### GET account_apps[](#get-account-apps "Permalink to this headline") + + +Retrieve details for all mobile apps that are associated with the specified ad account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/account_apps` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps` + +**Example Response[](#example-response "Permalink to this headline")** +```json + { + "request": { + "params": { + "account_ids": [ + "18ce54d4x5t" + ] + } + }, + "next_cursor": null, + "data": [ + { + "app_store_identifier": "com.twitter.android", + "conversion_tracking_enabled": false, + "deep_link_pattern": "twitter://", + "id": "4x", + "created_at": "2019-06-20T22:36:16Z", + "updated_at": "2021-10-19T20:05:29Z", + "os_type": "Android", + "deleted": false + } + ] + } +``` +### Account History + + + +#### GET accounts/:account\_id/account\_history[](#get-accounts-account-id-account-history "Permalink to this headline") + + +Retrieve a summary of changes made to the `entity_id` specified in the request. + +**Note**: This endpoint is currently in beta and requires allowlisting. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/account_history` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| account_id
_required_ | The identifier for the leveraged account.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| entity_type
_required_ | The entity type to retrieve data for.

Type: enum

Example: `PROMOTED_TWEET`
Possible values: `CAMPAIGN`, `LINE_ITEM`, `PROMOTED_TWEET`, `TARGETING_CRITERIA`, `PROMOTED_ACCOUNT` | +| entity_id
_required_ | The specific entitiy to retrieve data for.

Type: string

Example: `8u94t` | +| start_time
_required_ | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-19T07:00:00Z` | +| end_time
_required_ | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: `2017-05-26T07:00:00Z` | +| user_id
_optional_ | Scopes the response to a specific user.

Type: long

Example: `3271358660` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1` + +**Example Response[](#example-response "Permalink to this headline")** + +```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" + } + ] + } +``` +### Advertiser Business Categories + + +#### GET advertiser\_business\_categories[](#get-advertiser-business-categories "Permalink to this headline") + +Request the valid advertiser business `categories` for Ad Groups (`line_items`) to describe an advertiser's brand to publishers. + +Note: These categories apply only to `line_items` with the `PREROLL_VIEWS` objective and are separate from the `content_categories` used for targeting criteria. + +Each `advertiser_business_categories` represents a collection of [IAB Categories](/x-ads-api/campaign-management/reference#iab-categories). When creating an Ad Group with the `PREROLL_VIEWS` objective, one or two `advertiser_business_categories` must be set for the Ad Group. This can be done by setting the value of the `categories` request parameter on the [line item](/x-ads-api/campaign-management/reference#line-items) endpoint to the set of corresponding `iab_categories` available through this endpoint. + +Additional details can be found in the [Video Views Preroll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective) + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/advertiser_business_categories` + +**Parameters[](#parameters "Permalink to this headline")** + +No request parameters + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/advertiser_business_categories` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "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" + ] + } + ] + } +``` +### Audience Estimate + + +POST accounts/:account\_id/audience\_estimate[](#post-accounts-account-id-audience-estimate "Permalink to this headline") + +#### Determine the approximate audience size of your campaigns. + +This endpoint accepts an array of JSON objects containing the parameters for the targeting criteria objects. A list of required and optional targeting criteria parameters are available on the [POST accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#post-accounts-account-id-targeting-criteria) endpoint. Requests must be HTTP POST with a JSON content body with a `Content-Type: application/json` header. + +**Note**: It is required that you specify at least one **primary** targeting criterion; you can see a list of all primary targeting criteria in our [campaigns targeting page](/x-ads-api/campaign-management/reference#targeting). + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/audience_estimate` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| targeting_criteria
_required_ | A JSON object containing all the parameters for the targeting criteria objects. A list of required and optional targeting criteria parameters are available on the [POST accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#post-accounts-account-id-targeting-criteria) endpoint. | +| operator_type
_optional_ | Specify the relationship that the targeting criterion should have. For example, to set negated targeting, use `operator_type=NE`.

Type: enum

Possible values: `EQ`, `NE`

Default: `EQ` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate` + +```json + { + "targeting_criteria": [ + { + "targeting_type": "BROAD_KEYWORD", + "targeting_value": "nba", + "operator_type": "EQ" + }, + { + "targeting_type": "BROAD_KEYWORD", + "targeting_value": "tech", + "operator_type": "NE" + }, + { + "targeting_type": "LOCATION", + "targeting_value": "96683cc9126741d1", + "operator_type": "EQ" + }, + { + "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER", + "targeting_value": "14230524" + }, + { + "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER", + "targeting_value": "90420314" + } + ] + } +``` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "targeting_criteria": null, + "account_id": "18ce54d4x5t" + } + }, + "data": { + "audience_size": { + "min": 38236294, + "max": 42261167 + } + } + } +``` +### Authenticated User Access + + +#### GET accounts/:account\_id/authenticated\_user_access[](#get-accounts-account-id-authenticated-user-access "Permalink to this headline") + +Retrieve the permissions of the currently authenticated user (access_token) as they relate to the specified ads account. These permissions match those exposed on ads.x.com. + +Possible values include: + +* `ACCOUNT_ADMIN`: Full access to modify campaigns and view stats, including the ability to add or remove users and change settings +* `AD_MANAGER`: Full access to modify campaigns and view stats, but cannot add or remove users or change settings +* `CREATIVE_MANAGER`: Access to modify creatives and view previews, but no access to create or modify campaigns +* `CAMPAIGN_ANALYST`: Access to view campaigns and view stats, but no access to create or modify campaigns +* `ANALYST` ("Organic Analyst" on ads.x.com): Access to view organic analytics and audience insights, but no access to create, modify, or view campaigns +* `PARTNER_AUDIENCE_MANAGER`: API-only access to view and modify data partner audiences, but no access to campaigns, creatives, or other audience types. + +In addition, the `TWEET_COMPOSER` permission indicates that the authenticated user can create nullcasted (or "Promoted-only") Tweets on behalf of the advertiser. This is only available for users with `ACCOUNT_ADMIN`, `AD_MANAGER`, or `CREATIVE_MANAGER` access. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/authenticated_user_access` + +**Parameters[](#parameters "Permalink to this headline")** + +None + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/authenticated_user_access` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "user_id": "2417045708", + "permissions": [ + "ACCOUNT_ADMIN", + "TWEET_COMPOSER" + ] + }, + "request": { + "params": { + "account_id": "18ce54d4x5t" + } + } + } +``` + +### Bidding Rules + + +#### GET bidding_rules[](#get-bidding-rules "Permalink to this headline") + +Retrieve the bidding rules for some or all currencies. The response will indicate the minimum and maximum CPE (cost-per-engagement) bids. + +While these bidding rules change rarely, it is suggested that your systems refresh from these endpoints at least monthly. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/bidding_rules` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| currency
_optional_ | The type of a currency to filter results by, identified using [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217). This is a three-letter string "USD" or "EUR". Omit this parameter to retrieve all bidding rules. associated with the authenticating user.

Type: string

Example: `USD` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/bidding_rules?currency=USD` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "currency": "USD" + } + }, + "data_type": "bidding_rule", + "data": [ + { + "currency": "USD", + "minimum_cpe_bid_local_micro": 10000, + "maximum_cpe_bid_local_micro": 1000000000, + "minimum_denomination": 10000 + } + ], + "total_count": 1 + } +``` +### Campaigns + + +#### GET accounts/:account_id/campaigns[](#get-accounts-account-id-campaigns "Permalink to this headline") + +Retrieve details for some or all campaigns associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/campaigns` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#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](/x-ads-api/introduction) 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "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[](#get-accounts-account-id-campaigns-campaign-id "Permalink to this headline") + +Retrieve a specific campaign associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "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[](#post-accounts-account-id-campaigns "Permalink to this headline") + +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 X Account Manager. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/campaigns` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#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](/x-ads-api/campaign-management/reference#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[](#example-request "Permalink to this headline")** + +`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[](#example-response "Permalink to this headline")** + +```json + { + "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[](#post-batch-accounts-account-id-campaigns "Permalink to this headline") + +Allows the batch creation of new [campaigns](#post-accounts-account-id-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[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/batch/accounts/:account_id/campaigns` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](#post-accounts-account-id-campaigns). | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns` + +```json + [ + { + "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[](#example-response "Permalink to this headline")** + +```json + { + "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[](#put-accounts-account-id-campaigns-campaign-id "Permalink to this headline") + +Update the specified campaign associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#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](/x-ads-api/campaign-management/reference#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[](#example-request "Permalink to this headline")** + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "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-accounts-account-id-campaigns-campaign-id "Permalink to this headline") + +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[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#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[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "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 + } + } +``` +### Content Categories + + +#### GET content_categories[](#get-content-categories "Permalink to this headline") + +Request the valid content `categories` to be set as `targeting_criteria` for a line item. + +Each `content_category` maps to one or more [IAB Categories](/x-ads-api/campaign-management/reference#iab-categories). This can be done by setting the `targeting_type` to `IAB_CATEGORY` on the batch `targeting_critera` endpoint to include the set of corresponding `iab_categories` returned by the `content_categories` request. Failure to do so will result in a validation error. + +Publisher details for each of these content categories can be retrieved using the [GET publishers](/x-ads-api/campaign-management/reference#publishers) endpoint. + +Additional details can be found in the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective). + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/content_categories` + +**Parameters[](#parameters "Permalink to this headline")** + +No request parameters + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/content_categories` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": {} + }, + "next_cursor": null, + "data": [ + { + "name": "Automotive (Cars, Trucks, Racing)", + "id": "ru", + "iab_categories": [ + "IAB2" + ], + "publishers_in_last_thirty_days": 12, + "videos_monetized_in_last_thirty_days": 316 + }, + { + "name": "Comedy", + "id": "sk", + "iab_categories": [ + "IAB1-4" + ], + "publishers_in_last_thirty_days": 19, + "videos_monetized_in_last_thirty_days": 174 + }, + { + "name": "Digital Creators", + "id": "sl", + "iab_categories": [ + "IAB25-1" + ], + "publishers_in_last_thirty_days": 110, + "videos_monetized_in_last_thirty_days": 1257 + }, + { + "name": "Entertainment & Pop Culture", + "id": "sm", + "iab_categories": [ + "IAB1-1", + "IAB1-2", + "IAB1-3", + "IAB1-5" + ], + "publishers_in_last_thirty_days": 120, + "videos_monetized_in_last_thirty_days": 3482 + }, + { + "name": "Financial & Business News", + "id": "sn", + "iab_categories": [ + "IAB3", + "IAB13", + "IAB21" + ], + "publishers_in_last_thirty_days": 29, + "videos_monetized_in_last_thirty_days": 1461 + }, + { + "name": "Food & Drink", + "id": "so", + "iab_categories": [ + "IAB8-8", + "IAB8-12", + "IAB8-17", + "IAB8-2", + "IAB8-3", + "IAB8-7", + "IAB8-11", + "IAB8-4", + "IAB8-14", + "IAB8-10", + "IAB8-15", + "IAB8-13", + "IAB8-9", + "IAB8-16", + "IAB8-6", + "IAB8-1" + ], + "publishers_in_last_thirty_days": 24, + "videos_monetized_in_last_thirty_days": 516 + }, + { + "name": "Lifestyle (Fashion, Travel, Wellness)", + "id": "sp", + "iab_categories": [ + "IAB16", + "IAB9-21", + "IAB9-4", + "IAB9-25", + "IAB9-8", + "IAB4", + "IAB9-3", + "IAB9-15", + "IAB7", + "IAB6", + "IAB9-11", + "IAB9-16", + "IAB9-7", + "IAB9-20", + "IAB9-24", + "IAB9-17", + "IAB9-12", + "IAB9-31", + "IAB9-27", + "IAB10", + "IAB9-10", + "IAB9-23", + "IAB9-6", + "IAB9-18", + "IAB9-13", + "IAB9-1", + "IAB9-28", + "IAB20", + "IAB9-5", + "IAB9-26", + "IAB22", + "IAB23", + "IAB9-9", + "IAB9-22", + "IAB18", + "IAB9-2", + "IAB9-19", + "IAB9-14", + "IAB9-29" + ], + "publishers_in_last_thirty_days": 67, + "videos_monetized_in_last_thirty_days": 2412 + }, + { + "name": "Music", + "id": "sq", + "iab_categories": [ + "IAB1-6" + ], + "publishers_in_last_thirty_days": 31, + "videos_monetized_in_last_thirty_days": 518 + }, + { + "name": "News & Current Events", + "id": "sr", + "iab_categories": [ + "IAB12", + "IAB14" + ], + "publishers_in_last_thirty_days": 125, + "videos_monetized_in_last_thirty_days": 5507 + }, + { + "name": "Politics", + "id": "s4", + "iab_categories": [ + "IAB11" + ], + "publishers_in_last_thirty_days": 19, + "videos_monetized_in_last_thirty_days": 1402 + }, + { + "name": "Science & Education", + "id": "ss", + "iab_categories": [ + "IAB5", + "IAB15" + ], + "publishers_in_last_thirty_days": 7, + "videos_monetized_in_last_thirty_days": 132 + }, + { + "name": "Sports", + "id": "se", + "iab_categories": [ + "IAB17" + ], + "publishers_in_last_thirty_days": 403, + "videos_monetized_in_last_thirty_days": 18281 + }, + { + "name": "Technology", + "id": "sg", + "iab_categories": [ + "IAB19" + ], + "publishers_in_last_thirty_days": 13, + "videos_monetized_in_last_thirty_days": 1089 + }, + { + "name": "Television", + "id": "sh", + "iab_categories": [ + "IAB1-7" + ], + "publishers_in_last_thirty_days": 58, + "videos_monetized_in_last_thirty_days": 1307 + }, + { + "name": "Esports & Video Games", + "id": "s0", + "iab_categories": [ + "IAB9-30" + ], + "publishers_in_last_thirty_days": 109, + "videos_monetized_in_last_thirty_days": 1844 + } + ], + "total_count": 15 + } +``` +### Curated Categories + + +#### GET accounts/:account\_id/curated\_categories[](#get-accounts-account-id-curated-categories "Permalink to this headline") + +Retrieve a list of available Curated Categories for the given `country_codes` + +Each `curated_category` is only available in specific countries specified by the `country_codes` in the response. + +Additional details can be found in the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective). + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/curated_categories` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| country_codes
_required_ | Scope the response to just the desired countries by specifying a comma-separated list of two letter ISO country codes. Up to 200 IDs may be provided.

Type: string

Example: `US` | +| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "country_codes": [ + "US" + ], + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "name": "Basketball", + "description": "Run next to the best of everyday basketball content including college teams, professional teams, and the top sports media handles sharing on and off-season basketball video.", + "country_codes": [ + "US" + ], + "publisher_user_ids": [ + "20265254", + "378174762", + "900368808", + "18939563", + "18371803", + "18360370", + "770658432928079872", + "11026952", + "37085464", + "16212685", + "57422635", + "281669945", + "7117962", + "23065057", + "41688179", + "29779226", + "900280416", + "364460082", + "902030382", + "19409270", + "19077044", + "18139461", + "14992591", + "66753565", + "667563", + "16727749", + "40941404", + "18481113", + "791598918", + "16201775", + "15900167", + "45891626", + "191894553", + "2181233851", + "34352904", + "171483987", + "454122399", + "57415242", + "19263978", + "902089998", + "423540866", + "2715223320", + "22185437", + "17292143", + "55590247", + "66757066", + "22642626", + "41604618", + "87275465", + "22643259", + "32414973", + "73406718", + "20346956", + "413422891", + "45412765", + "19537303", + "459511725", + "30954864", + "21308488", + "18552281", + "19924520", + "24903350", + "851142163", + "26270913", + "20444254", + "26074296", + "6395222", + "15537451", + "28672101", + "38053254", + "24925573", + "19564719", + "18164425", + "22815383", + "20196159" + ], + "id": "929wbl6ymlfk", + "created_at": "2019-11-08T21:12:47Z", + "updated_at": "2021-03-09T20:36:44Z", + "videos_monetized_in_last_thirty_days": 2446 + }, + { + "name": "Gaming Personalities", + "description": "Run next to the best of everyday gaming content exclusively from a list of some of online gaming’s biggest and most loved digital creators.", + "country_codes": [ + "US" + ], + "publisher_user_ids": [ + "90779436", + "268270621", + "567167802", + "246596682", + "474919140", + "284422688", + "185909682", + "4767225325", + "2559865245", + "186888760", + "161418822", + "141021153", + "352881953", + "1117931702", + "146556805", + "357294577", + "234526497", + "266687361", + "214201922", + "9451052", + "2163885564", + "2231422037", + "116952434", + "399909209", + "15993650", + "974356091193741312", + "210839744", + "2313002094", + "159916388", + "3258981481", + "231992478", + "182236262", + "386884916", + "22705686", + "4140881832", + "995979576", + "2244953047", + "311775629", + "98821255", + "2733210014", + "2741078150" + ], + "id": "94ngssfrr01x", + "created_at": "2019-12-02T20:45:12Z", + "updated_at": "2021-03-09T20:18:13Z", + "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", + "25084916", + "764347046", + "19853312", + "348590880" + ], + "id": "8tujg1lvi8sn", + "created_at": "2019-08-15T20:48:51Z", + "updated_at": "2021-03-09T20:34:13Z", + "videos_monetized_in_last_thirty_days": 254 + }, + { + "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 + }, + { + "name": "Soccer", + "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.", + "country_codes": [ + "US" + ], + "publisher_user_ids": [ + "21677316", + "20636347", + "4704552148", + "14573900", + "22556296", + "1415791555", + "107146095", + "17288520", + "213474069", + "17493398", + "44990136", + "452155423", + "17744542", + "16303450", + "2841146601", + "2413176055", + "29739264", + "38580532", + "953476292913106945", + "27092557", + "86356439", + "34613288", + "3170659367", + "119593082", + "73412535", + "627586654", + "15891449", + "23011345", + "96951800", + "15997022", + "16960789", + "21919642", + "102965285", + "17224076", + "36432200", + "1410055968" + ], + "id": "9ddrgesiap6o", + "created_at": "2020-02-28T22:43:26Z", + "updated_at": "2021-01-26T17:54:55Z", + "videos_monetized_in_last_thirty_days": 421 + } + ], + "total_count": 9 + } +``` + +#### GET accounts/:account\_id/curated\_categories/:curated\_category\_id[](#get-accounts-account-id-curated-categories-curated-category-id "Permalink to this headline") + +Retrieve details for a specific `curated_category_id` + +Each `curated_category` is only available in specific countries specified by the `country_codes` in the response. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/curated_categories/:curated_category_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| curated\_category\_id
_required_ | A reference to the Curated Category you are operating with in the request.

Type: string

Example: `9ddrgesiap6o` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "id": "9ddrgesiap6o", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "name": "Soccer", + "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.", + "country_codes": [], + "publisher_user_ids": [ + "21677316", + "20636347", + "4704552148", + "14573900", + "22556296", + "1415791555", + "107146095", + "17288520", + "213474069", + "17493398", + "44990136", + "452155423", + "17744542", + "16303450", + "2841146601", + "2413176055", + "29739264", + "38580532", + "953476292913106945", + "27092557", + "86356439", + "34613288", + "3170659367", + "119593082", + "73412535", + "627586654", + "15891449", + "23011345", + "96951800", + "15997022", + "16960789", + "21919642", + "102965285", + "17224076", + "36432200", + "1410055968" + ], + "id": "9ddrgesiap6o", + "created_at": "2020-02-28T22:43:26Z", + "updated_at": "2021-01-26T17:54:55Z", + "videos_monetized_in_last_thirty_days": 421 + } + } +``` +### Features + + +#### GET accounts/:account_id/features[](#get-accounts-account-id-features "Permalink to this headline") + +Retrieve the collection of granted features accessible by this ads account. Features are indicated by a descriptive feature key and are only exposed on this endpoint if they are introduced in beta or an otherwise limited release and are available in the Ads API. Features that do not meet this criteria will not be exposed on this endpoint. + +**Note**: This endpoint serves to aid Ads API ecosystem development by improving visibility into client access to beta releases. API developers can not request access to features on behalf of an advertiser. These requests can only be made by the advertiser to their X account manager. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/features` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| feature_keys
_optional_ | An optional parameter that enables querying for a specific feature key. Requests may include multiple comma-separated keys.

**Note**: Only the features that are accessible by this account will be included in the response.

Type: enum

Possible values: `REACH_AND_FREQUENCY_ANALYTICS`, `REACH_FREQUENCY_CAP`, `WEBSITE_CLICKS_CPM_BILLING` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t" + } + }, + "data": [ + "CITY_TARGETING", + "CONVERSATION_CARD", + "PROMOTED_MEDIA_POLLS", + "REACH_AND_FREQUENCY_ANALYTICS", + "REACH_FREQUENCY_CAP", + "UNIVERSAL_LOOKALIKE" + ] + } +``` + +#### POST accounts/:account_id/features[](#post-accounts-account-id-features "Permalink to this headline") + +**SANDBOX ONLY** + +Add a feature to a sandbox account. + +The up to date list of account features may be retrieved via the [GET accounts/:account_id/features](#get-accounts-account-id-features) endpoint. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api-sandbox.x.com/12/accounts/:account_id/features` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `gq180y` | +| feature_keys
_required_ | A comma-separated list of account features to add to the account.

Type: enum

Possible values: `AGE_TARGETING`, `ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE`, `AWARENESS_OBJECTIVE`, `BRAND_TPN`, `CHARGE_FOR_GOOD_CLICK`, `CONVERSATION_CARD`, `CONVERSATION_CARD_FOUR_OPTIONS`, `CONVERSATION_CARD_UNLOCK`, `CPI_CHARGING`, `DIRECT_MESSAGE_CARD`, `DR_TAP`, `ENGAGER_RETARGETING`, `EVENT_TARGETING`, `INSTALLED_APP_CATEGORY_TARGETING`, `MOBILE_CONVERSION_TRANSACTION_VALUE`, `OPTIMIZED_ACTION_BIDDING`, `REACH_AND_FREQUENCY_ANALYTICS`, `REACH_FREQUENCY_CAP`, `VALIDATED_AGE_TARGETING`, `VIDEO_VIEWS_MIDROLL_OBJECTIVE`, `PREROLL_VIEWS_OBJECTIVE`, `VIDEO_APP_DOWNLOAD_CARD` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "gq180y", + "feature_keys": [ + "VALIDATED_AGE_TARGETING" + ] + } + }, + "data": [ + "ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE", + "AWARENESS_OBJECTIVE", + "CPI_CHARGING", + "EVENT_TARGETING", + "INSTALLED_APP_CATEGORY_TARGETING", + "MOBILE_CONVERSION_TRANSACTION_VALUE", + "OPTIMIZED_ACTION_BIDDING", + "VALIDATED_AGE_TARGETING", + "VIDEO_APP_DOWNLOAD_CARD" + ] + } +``` + +#### DELETE accounts/:account_id/features[](#delete-accounts-account-id-features "Permalink to this headline") + +**SANDBOX ONLY** + +Remove a feature from a sandbox account. + +The up to date list of account features may be retrieved via the [GET accounts/:account_id/features](#get-accounts-account-id-features) endpoint. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api-sandbox.x.com/12/accounts/:account_id/features` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `gq180y` | +| feature_keys
_required_ | A comma-separated list of account features to remove from the account.

Type: enum

Possible values: `AGE_TARGETING`, `ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE`, `AWARENESS_OBJECTIVE`, `BRAND_TPN`, `CHARGE_FOR_GOOD_CLICK`, `CONVERSATION_CARD`, `CONVERSATION_CARD_FOUR_OPTIONS`, `CONVERSATION_CARD_UNLOCK`, `CPI_CHARGING`, `DIRECT_MESSAGE_CARD`, `DR_TAP`, `ENGAGER_RETARGETING`, `EVENT_TARGETING`, `INSTALLED_APP_CATEGORY_TARGETING`, `MOBILE_CONVERSION_TRANSACTION_VALUE`, `OPTIMIZED_ACTION_BIDDING`, `REACH_AND_FREQUENCY_ANALYTICS`, `REACH_FREQUENCY_CAP`, `VALIDATED_AGE_TARGETING`, `VIDEO_VIEWS_MIDROLL_OBJECTIVE`, `PREROLL_VIEWS_OBJECTIVE`, `VIDEO_APP_DOWNLOAD_CARD` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "gq180y", + "feature_keys": [ + "PREROLL_VIEWS_OBJECTIVE" + ] + } + }, + "data": [ + "CPI_CHARGING", + "EVENT_TARGETING", + "INSTALLED_APP_CATEGORY_TARGETING", + "MOBILE_CONVERSION_TRANSACTION_VALUE", + "OPTIMIZED_ACTION_BIDDING", + "VIDEO_APP_DOWNLOAD_CARD" + ] + } +``` +### Funding Instruments + + +#### GET accounts/:account\_id/funding\_instruments[](#get-accounts-account-id-funding-instruments "Permalink to this headline") + +Retrieve details for some or all funding instruments associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/funding_instruments` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| funding\_instrument\_ids
_optional_ | Scope the response to just the desired 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](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "start_time": "2016-07-22T04:24:04Z", + "description": "Visa ending in 0650", + "credit_limit_local_micro": 200000000, + "end_time": null, + "id": "lygyi", + "entity_status": "ACTIVE", + "account_id": "18ce54d4x5t", + "reasons_not_able_to_fund": [], + "io_header": null, + "currency": "USD", + "funded_amount_local_micro": 645940000, + "created_at": "2016-07-22T04:24:04Z", + "type": "CREDIT_CARD", + "able_to_fund": true, + "updated_at": "2017-04-05T00:25:13Z", + "credit_remaining_local_micro": null, + "deleted": false + } + ] + } +``` + +#### GET accounts/:account\_id/funding\_instruments/:funding\_instrument\_id[](#get-accounts-account-id-funding-instruments-funding-instrument-id "Permalink to this headline") + +Retrieve a specific funding instrument associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/funding_instruments/:id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| funding\_instrument\_id
_required_ | A reference to the funding instrument you are operating with in the request.

Type: string

Example: `lygyi` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "funding_instrument_id": "lygyi", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "start_time": "2016-07-22T04:24:04Z", + "description": "Visa ending in 0650", + "credit_limit_local_micro": 200000000, + "end_time": null, + "id": "lygyi", + "entity_status": "ACTIVE", + "account_id": "18ce54d4x5t", + "reasons_not_able_to_fund": [], + "io_header": null, + "currency": "USD", + "funded_amount_local_micro": 645940000, + "created_at": "2016-07-22T04:24:04Z", + "type": "CREDIT_CARD", + "able_to_fund": true, + "updated_at": "2017-04-05T00:25:13Z", + "credit_remaining_local_micro": null, + "deleted": false + } + } +``` + +#### POST accounts/:account\_id/funding\_instruments[](#post-accounts-account-id-funding-instruments "Permalink to this headline") + +**SANDBOX ONLY** + +Create a funding instrument in the sandbox environment. + +There is no risk of incurring costs while using a sandbox funding instrument. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `gq1844` | +| currency
_required_ | The currency, expressed in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217).

Type: string

Example: `USD` | +| start_time
_required_ | The date for the funding instrument to become active and usable, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

Type: string

Example: `2017-05-19T07:00:00Z` | +| type
_required_ | The type of funding instrument to create.

Type: enum

Possible values: `AGENCY_CREDIT_LINE`, `CREDIT_CARD`, `CREDIT_LINE`, `INSERTION_ORDER`, `PARTNER_MANAGED` | +| end_time
_sometimes required_ | The date for the funding instrument to become inactive, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

Type: string

Example: `2017-05-26T07:00:00Z` | +| credit\_limit\_local_micro
_optional_ | The total credit available against this funding instrument.

**Note**: Only applicable to some funding instrument types.

Type: long

Example: `37500000` | +| funded\_amount\_local_micro
_optional_ | The total budget amount allocated to this funding instrument.

**Note**: Only applicable to some funding instrument types.

Type: long

Example: `37500000` | + +**Example Request[](#example-request "Permalink to this headline")** + +`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` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "start_time": "2017-07-10T00:00:00Z", + "description": "(no payment method has been set up yet)", + "credit_limit_local_micro": null, + "end_time": "2018-01-10T00:00:00Z", + "id": "hxtet", + "entity_status": "ACTIVE", + "account_id": "gq1844", + "reasons_not_able_to_fund": [], + "io_header": null, + "currency": "USD", + "funded_amount_local_micro": 140000000000, + "created_at": "2017-09-09T05:23:28Z", + "type": "INSERTION_ORDER", + "able_to_fund": true, + "updated_at": "2017-09-09T05:23:28Z", + "credit_remaining_local_micro": null, + "deleted": false + }, + "request": { + "params": { + "start_time": "2017-07-10T00:00:00Z", + "end_time": "2018-01-10T00:00:00Z", + "account_id": "gq1844", + "currency": "USD", + "funded_amount_local_micro": 140000000000, + "type": "INSERTION_ORDER" + } + } + } +``` + +#### DELETE accounts/:account\_id/funding\_instruments/:funding\_instrument\_id[](#delete-accounts-account-id-funding-instruments-funding-instrument-id "Permalink to this headline") + +**SANDBOX ONLY** + +Delete a funding instrument in the sandbox environment. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `gq1844` | +| funding\_instrument\_id
_required_ | A reference to the funding instrument you are operating with in the request.

Type: string

Exampple: `hxt82` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "start_time": "2017-08-30T19:23:47Z", + "description": "(no payment method has been set up yet)", + "credit_limit_local_micro": 500000000, + "end_time": null, + "id": "hxt82", + "entity_status": "ACTIVE", + "account_id": "gq1844", + "reasons_not_able_to_fund": [ + "DELETED" + ], + "io_header": null, + "currency": "USD", + "funded_amount_local_micro": null, + "created_at": "2017-08-30T19:23:47Z", + "type": "CREDIT_CARD", + "able_to_fund": false, + "updated_at": "2017-09-09T02:08:30Z", + "credit_remaining_local_micro": null, + "deleted": true + }, + "request": { + "params": { + "funding_instrument_id": "hxt82", + "account_id": "gq1844" + } + } + } +``` +### IAB Categories + + +#### GET iab_categories[](#get-iab-categories "Permalink to this headline") + +Request the valid app `categories` for ad groups (`line_items`). + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/iab_categories` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| 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 categories. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `gc-ddf4a` | +| 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/iab_categories?count=2` + +**Example Response[](#example-response "Permalink to this headline")** + +```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 + } + } + } +``` +### Line Items + + +#### GET accounts/:account\_id/line\_items[](#get-accounts-account-id-line-items "Permalink to this headline") + +Retrieve details for some or all line items associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_items` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#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 line items under specific campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8gdx6` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| funding\_instrument\_ids
_optional_ | Scope the response to just the line items under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `lygyi` | +| line\_item\_ids
_optional_ | Scope the response to just the desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8v7jo` | +| 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "line_item_ids": [ + "itttx" + ] + } + }, + "next_cursor": null, + "data": [ + { + "advertiser_user_id": "756201191646691328", + "name": "li-18", + "placements": [ + "ALL_ON_TWITTER" + ], + "start_time": "2021-02-16T00:00:00Z", + "bid_amount_local_micro": 320000, + "advertiser_domain": null, + "target_cpa_local_micro": null, + "primary_web_event_tag": null, + "goal": "ENGAGEMENT", + "daily_budget_amount_local_micro": null, + "product_type": "PROMOTED_TWEETS", + "end_time": null, + "funding_instrument_id": "lygyi", + "bid_strategy": "MAX", + "duration_in_days": null, + "standard_delivery": null, + "total_budget_amount_local_micro": null, + "objective": "ENGAGEMENTS", + "id": "itttx", + "entity_status": "PAUSED", + "automatic_tweet_promotion": null, + "frequency_cap": null, + "android_app_store_identifier": null, + "categories": [], + "currency": "USD", + "pay_by": "ENGAGEMENT", + "created_at": "2021-02-23T23:37:54Z", + "ios_app_store_identifier": null, + "updated_at": "2022-06-01T02:01:18Z", + "campaign_id": "f4z6x", + "creative_source": "MANUAL", + "deleted": false + } + ] + } +``` + +#### GET accounts/:account\_id/line\_items/:line\_item\_id[](#get-accounts-account-id-line-items-line-item-id "Permalink to this headline") + +Retrieve a specific line item associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "line_item_id": "itttx", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "advertiser_user_id": "756201191646691328", + "name": "li-18", + "placements": [ + "ALL_ON_TWITTER" + ], + "start_time": "2021-02-16T00:00:00Z", + "bid_amount_local_micro": 320000, + "advertiser_domain": null, + "target_cpa_local_micro": null, + "primary_web_event_tag": null, + "goal": "ENGAGEMENT", + "daily_budget_amount_local_micro": null, + "product_type": "PROMOTED_TWEETS", + "end_time": null, + "funding_instrument_id": "lygyi", + "bid_strategy": "MAX", + "duration_in_days": null, + "standard_delivery": null, + "total_budget_amount_local_micro": null, + "objective": "ENGAGEMENTS", + "id": "itttx", + "entity_status": "PAUSED", + "automatic_tweet_promotion": null, + "frequency_cap": null, + "android_app_store_identifier": null, + "categories": [], + "currency": "USD", + "pay_by": "ENGAGEMENT", + "created_at": "2021-02-23T23:37:54Z", + "ios_app_store_identifier": null, + "updated_at": "2022-06-01T02:01:18Z", + "campaign_id": "f4z6x", + "creative_source": "MANUAL", + "deleted": false + } + } +``` + +#### POST accounts/:account\_id/line\_items[](#post-accounts-account-id-line-items "Permalink to this headline") + +Create a line item associated with the specified campaign belonging to the current account. + +All line items within a campaign must be of the same `product_type` and `objective`. + +When using the `PROMOTED_ACCOUNT` product type, associating a Tweet with the `line_item` will add timeline placements on mobile in addition to the standard `PROMOTED_ACCOUNT` placement. + +Setting either `android_app_store_identifier` or `ios_app_store_identifier` will automatically add the targeting criteria for the line item matching the mobile app being promoted; for example, passing in `ios_app_store_identifier` would add `PLATFORM` [targeting criteria](/x-ads-api/campaign-management/reference#targeting-options) for `iOS`. + +**Note**: There is a limit of 100 line items per campaign and 256 active line items across all campaigns. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_items` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| campaign_id
_required_ | The identifier for the campaign to create the line item under.

Type: string

Example: `8slvg` | +| end_time
_required_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will stop serving.

Type: string

Example: `2017-10-05T00:00:00Z` | +| objective
_required_ | The campaign objective for this line item.

Type: enum

Possible values: `APP_ENGAGEMENTS`, `APP_INSTALLS`, `REACH`, `FOLLOWERS`, `ENGAGEMENTS`, `VIDEO_VIEWS`, `PREROLL_VIEWS`, `WEBSITE_CLICKS` | +| placements
_required_ | The placement location(s) for this line item to display in. Specify a comma-separated list of placement values.

Type: enum

Possible values: `ALL_ON_TWITTER`, `PUBLISHER_NETWORK`, `TAP_BANNER`, `TAP_FULL`, `TAP_FULL_LANDSCAPE`, `TAP_NATIVE`, `TAP_MRECT`,`TWITTER_PROFILE`, `TWITTER_REPLIES`, `TWITTER_SEARCH`, `TWITTER_TIMELINE` | +| product_type
_required_ | The type of promoted product that this line item will contain.

Type: enum

Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS` | +| start_time
_required_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.

Type: string

Example: `2017-07-05T00:00:00Z` | +| advertiser_domain
_sometimes required_ | The website domain for this advertiser, without the protocol specification.

**Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.

Type: string

Example: `x.com` | +| android\_app\_store_identifier
_sometimes required_ | The Google App Store identifier for promoted applications.

**Note**: `APP_INSTALLS` and `APP_ENGAGEMENTS` objectives require setting at least one app store identifier -- either `android_app_store_identifier` or `ios_app_store_identifier`.

Type: string

Example: `com.twitter.android` | +| bid\_amount\_local_micro
_sometimes required_ | The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000.

**Note**: Required if `bid_strategy` is set to either `MAX` or `TARGET`

**Note**: Only values greater than zero are accepted.

Type: long

Example: `5500000` | +| categories
_sometimes required_ | The relevant IAB categories for this advertiser. See [GET iab_categories](/x-ads-api/campaign-management/reference#iab-categories).

**Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.

Type: string

Example: `IAB3-1` | +| ios\_app\_store_identifier
_sometimes required_ | The numeric portion of the Apple App Store identifier for promoted applications.

**Note**: `APP_INSTALLS` and `APP_ENGAGEMENTS` objectives require setting at least one app store identifier -- either `android_app_store_identifier` or `ios_app_store_identifier`.

Type: string

Example: `333903271` | +| primary\_web\_event_tag
_sometimes required_ | The identifier of the primary web event tag. Allows more accurate tracking of engagements for the campaign pertaining to this line item.

**Note**: Required when the line item's goal is set to `WEBSITE_CONVERSIONS`.

Type: string

Example: `nvo4z` | +| advertiser\_user\_id
_optional_ | The X user identifier for the handle promoting a `PREROLL_VIEWS` ad. Only certain client applications may use this parameter.

Type: string

Example: `312226591` | +| audience_expansion
_optional_ | Used to expand the reach of campaigns by targeting users similar to those already targeted.

**Note**: By default, no expansion will be applied.

Type: enum

Possible values: `BROAD`, `DEFINED`, `EXPANDED` | +| bid_strategy
_optional_ | The bidding mechanism.

`AUTO` automatically optimizes bidding based on daily budget and campaign flight dates.

`MAX` sets the maximum allowable bid and is **not** available when the objective is set to `REACH` or `FOLLOWERS`.

`TARGET` attempts to make daily bid averages within 20% of the specified `bid_amount_local_micro` and is available when the objective is set to `REACH`, `FOLLOWERS`, OR `WEBSITE_CLICKS`.

**Note**: If set to `AUTO`, `bid_amount_local_micro` will be ignored.

**Note**: Default based on objective.

Type: enum

Possible values: `AUTO`, `MAX`, `TARGET` | +| duration\_in\_days
_optional_ | The time period within which the `frequency_cap` is achieved.

Type: int

Possible values: `1`, `7`, `30` | +| entity_status
_optional_ | The line item 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 `REACH`, `ENGAGEMENTS`, `VIDEO_VIEWS`, and `PREROLL_VIEWS` objectives.

Type: int

Example: `5` | +| goal
_optional_ | The optimization setting to use with this line item.

The `APP_PURCHASES` option is available for `APP_INSTALL`. The `APP_CLICKS` and `APP_INSTALLS` options are available for both `APP_INSTALL` and `APP_ENGAGEMENTS` objectives and may require using a supported [MACT partner](https://business.x.com/en/help/campaign-setup/create-an-app-installs-or-app-engagement-campaign/mobile-app-conversion-tracking.html).

The `SITE_VISITS` option is only available with the `WEBSITE_CLICKS` objective.

**Note**: Default based on objective.

Type: enum

Possible values: `APP_CLICKS`, `APP_INSTALLS`, `APP_PURCHASES`,`ENGAGEMENT`, `FOLLOWERS`, `LINK_CLICKS`, `MAX_REACH`, `PREROLL`, `PREROLL_STARTS`, `REACH_WITH_ENGAGEMENT`, `SITE_VISITS`, `VIDEO_VIEW`, `VIEW_3S_100PCT`, `VIEW_6S`, `VIEW_15S`, `WEBSITE_CONVERSIONS` | +| name
_optional_ | The name for the line item.

Type: string

Example: `demo`

Min, Max length: `1`, `255` | +| pay_by
_optional_ | The unit to charge this line item by. This setting can only be modified for line items using the `APP_INSTALLS` objective.

**Note**: The default `pay_by` is automatically set based upon the campaign objective and line item's bid unit.

The `APP_INSTALLS` goal supports both `APP_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value.

The `LINK_CLICKS` goal supports both `LINK_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value but is not supported when setting `TARGET` for `bid_strategy`.

The `SITE_VISITS` goal supports `IMPRESSION` values.

Type: enum

Possible values: `APP_CLICK`, `IMPRESSION`, `LINK_CLICK` | +| standard_delivery
_optional_ | Enable standard or accelerated delivery. See [Budget Pacing](/x-ads-api/campaign-management/reference#budget-pacing) for more information on standard versus accelerated delivery. Only available when `budget_optimization` is set to `LINE_ITEM` for the parent campaign

Type: boolean

Default: `true`
Possible values: `true`, `false` | +| total\_budget\_amount\_local\_micro
_optional_ | The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000.

Type: long

Example: `37500000` | +| 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. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Only available when `budget_optimization` is set to `LINE_ITEM` for the parent campaign

**Note**: This should be less than or equal to the `total_budget_amount_local_micro`.

Type: long

Example: `5500000` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?campaign_id=hwtq0&objective=ENGAGEMENTS&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&bid_amount_local_micro=3210000&entity_status=PAUSED&daily_budget_amount_local_micro=1000000&start_time=2022-06-15` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "placements": [ + "ALL_ON_TWITTER" + ], + "start_time": "2022-06-15T00:00:00Z", + "bid_amount_local_micro": 3210000, + "daily_budget_amount_local_micro": 1000000, + "product_type": "PROMOTED_TWEETS", + "objective": "ENGAGEMENTS", + "entity_status": "PAUSED", + "account_id": "18ce54d4x5t", + "campaign_id": "hwtq0" + } + }, + "data": { + "advertiser_user_id": "756201191646691328", + "name": null, + "placements": [ + "ALL_ON_TWITTER" + ], + "start_time": "2022-06-15T00:00:00Z", + "bid_amount_local_micro": 3210000, + "advertiser_domain": null, + "target_cpa_local_micro": null, + "primary_web_event_tag": null, + "goal": "ENGAGEMENT", + "daily_budget_amount_local_micro": 1000000, + "product_type": "PROMOTED_TWEETS", + "end_time": null, + "bid_strategy": "MAX", + "duration_in_days": null, + "standard_delivery": true, + "total_budget_amount_local_micro": null, + "objective": "ENGAGEMENTS", + "id": "ml5vs", + "entity_status": "PAUSED", + "automatic_tweet_promotion": null, + "frequency_cap": null, + "android_app_store_identifier": null, + "categories": [], + "currency": "USD", + "pay_by": "ENGAGEMENT", + "created_at": "2022-06-03T23:47:20Z", + "ios_app_store_identifier": null, + "updated_at": "2022-06-03T23:47:20Z", + "campaign_id": "hwtq0", + "creative_source": "MANUAL", + "deleted": false + } + } +``` + +#### POST batch/accounts/:account\_id/line\_items[](#post-batch-accounts-account-id-line-items "Permalink to this headline") + +Allows the batch creation of new [line items](#post-accounts-account-id-line-items) 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 line item parameter) are shown in the response under the `operation_errors` object. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/batch/accounts/:account_id/line_items` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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 line item objects. For a list of required and optional line item parameters, see [here](#post-accounts-account-id-line-items). | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items` + +```json + [ + { + "operation_type":"Create", + "params":{ + "campaign_id":"8yn7m", + "objective":"ENGAGEMENTS", + "product_type":"PROMOTED_TWEETS", + "placements":"ALL_ON_TWITTER", + "bid_amount_local_micro":3210000, + "entity_status":"PAUSED" + } + } + ] +``` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "advertiser_user_id": "756201191646691328", + "name": null, + "placements": [ + "ALL_ON_TWITTER" + ], + "start_time": null, + "bid_amount_local_micro": 3210000, + "advertiser_domain": null, + "target_cpa_local_micro": null, + "primary_web_event_tag": null, + "goal": "ENGAGEMENT", + "daily_budget_amount_local_micro": null, + "product_type": "PROMOTED_TWEETS", + "end_time": null, + "funding_instrument_id": "lygyi", + "bid_strategy": "MAX", + "duration_in_days": null, + "standard_delivery": null, + "total_budget_amount_local_micro": null, + "objective": "ENGAGEMENTS", + "id": "9cqi0", + "entity_status": "PAUSED", + "automatic_tweet_promotion": null, + "frequency_cap": null, + "android_app_store_identifier": null, + "categories": [], + "currency": "USD", + "pay_by": "ENGAGEMENT", + "created_at": "2017-07-07T17:42:20Z", + "ios_app_store_identifier": null, + "updated_at": "2017-07-07T17:42:20Z", + "campaign_id": "8yn7m", + "creative_source": "MANUAL", + "deleted": false + } + ], + "request": [ + { + "params": { + "placements": [ + "ALL_ON_TWITTER" + ], + "bid_amount_local_micro": 3210000, + "product_type": "PROMOTED_TWEETS", + "objective": "ENGAGEMENTS", + "entity_status": "PAUSED", + "account_id": "18ce54d4x5t", + "campaign_id": "8yn7m" + }, + "operation_type": "Create" + } + ] + } +``` + +#### PUT accounts/:account\_id/line\_items/:line\_item\_id[](#put-accounts-account-id-line-items-line-item-id "Permalink to this headline") + +Update the specified line item associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | +| advertiser_domain
_optional_ | The website domain for this advertiser, without the protocol specification.

**Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.

Type: string

Example: `x.com` | +| advertiser\_user\_id
_optional_ | The Twitter user identifier for the handle promoting a `PREROLL_VIEWS` ad. Only certain client applications may use this parameter.

Type: string

Example: `312226591` | +| android\_app\_store_identifier
_optional_ | The Google App Store identifier for the promoted application.

**Note**: `APP_INSTALLS` and `APP_ENGAGEMENTS` objectives require setting at least one app store identifier -- either `android_app_store_identifier` or `ios_app_store_identifier`.

Type: string

Example: `com.twitter.android` | +| audience_expansion
_optional_ | Used to expand the reach of campaigns by targeting users similar to those already targeted.

Type: enum

Possible values: `BROAD`, `DEFINED`, `EXPANDED` | +| bid\_amount\_local_micro
_optional_ | The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000.

**Note**: Required if `bid_strategy` is set to either `MAX` or `TARGET`

**Note**: Only values greater than zero are accepted.

Type: long

Example: `140000` | +| bid_strategy
_optional_ | The bidding mechanism.

`AUTO` automatically optimizes bidding based on daily budget and campaign flight dates.

`MAX` sets the maximum allowable bid and is **not** available when the objective is set to `REACH` or `FOLLOWERS`.

`TARGET` attempts to make daily bid averages within 20% of the specified `bid_amount_local_micro` and is available when the objective is set to `REACH` or `WEBSITE_CLICKS`.

**Note**: If set to `AUTO`, `bid_amount_local_micro` will be ignored.

**Note**: Default based on objective.

Type: enum

Possible values: `AUTO`, `MAX`, `TARGET` | +| categories
_optional_ | The relevant IAB categories for this advertiser. See [GET iab_categories](/x-ads-api/campaign-management/reference#iab-categories).

**Note**: Required when the line item's placement is set to `PUBLISHER_NETWORK`.

Type: string

Example: `IAB3-1` | +| duration\_in\_days
_optional_ | The time period within which the `frequency_cap` is achieved.

Type: int

Possible values: `1`, `7`, `30` | +| entity_status
_optional_ | The line item status.

Type: enum

Possible values: `ACTIVE`, `PAUSED` | +| end_time
_optional_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will stop serving.

Type: string

Example: `2017-10-05T00:00:00Z` | +| frequency_cap
_optional_ | The maximum number of times an ad could be delivered to a user.

**Note**: Only supported for `REACH`, `ENGAGEMENTS`, `VIDEO_VIEWS`, and `PREROLL_VIEWS` objectives.

Type: int

Example: `5` | +| goal
_optional_ | The optimization setting to use with this line item. The `APP_PURCHASES` option is available for `APP_INSTALL`. The `APP_CLICKS` and `APP_INSTALLS` options are available for `APP_INSTALL` and `APP_ENGAGEMENTS` and may require using a supported [MACT partner](https://business.x.com/en/help/campaign-setup/create-an-app-installs-or-app-engagement-campaign/mobile-app-conversion-tracking.html).

**Note**: Default based on objective.

Type: enum

Possible values: `APP_CLICKS`, `APP_INSTALLS`, `APP_PURCHASES`, `ENGAGEMENT`, `FOLLOWERS`, `LINK_CLICKS`, `MAX_REACH`, `PREROLL`, `PREROLL_STARTS`, `REACH_WITH_ENGAGEMENT`, `VIDEO_VIEW`, `VIEW_3S_100PCT`, `VIEW_6S`, `VIEW_15S`, `WEBSITE_CONVERSIONS` | +| ios\_app\_store_identifier
_optional_ | The numeric portion of the Apple App Store identifier for promoted applications.

**Note**: `APP_INSTALLS` and `APP_ENGAGEMENTS` objectives require setting at least one app store identifier -- either `android_app_store_identifier` or `ios_app_store_identifier`.

Type: string

Example: `333903271` | +| name
_optional_ | The name for the line item.

Type: string

Example: `demo` | +| pay_by
_optional_ | The unit to charge this line item by. This setting can only be modified for line items using the `APP_INSTALLS` objective.

**Note**: The default `pay_by` is automatically set based upon the campaign objective and line item's bid unit.

The `APP_INSTALLS` goal supports both `APP_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value.

The `LINK_CLICKS` goal supports both `LINK_CLICK` and `IMPRESSION` values. `IMPRESSION` is the default value but is not supported when setting `TARGET` for `bid_strategy`.

The `SITE_VISITS` goal supports `IMPRESSION` values.

Type: enum

Possible values: `APP_CLICK`, `IMPRESSION`, `LINK_CLICK` | +| start_time
_optional_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.

Type: string

Example: `2017-07-05T00:00:00Z` | +| total\_budget\_amount\_local\_micro
_optional_ | The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000.

Type: long

Example: `37500000` | +| 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. Only available when `budget_optimization` is set to `LINE_ITEM` for the parent campaign

**Note**: This should be less than or equal to the `total_budget_amount_local_micro`.

Type: long

Example: `5500000` | + +**Example Request[](#example-request "Permalink to this headline")** + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "line_item_id": "9cqi0", + "bid_amount_local_micro": 140000, + "account_id": "18ce54d4x5t" + } + }, + "data": { + "advertiser_user_id": "756201191646691328", + "name": null, + "placements": [ + "ALL_ON_TWITTER" + ], + "start_time": "2017-07-10T00:00:00Z", + "bid_amount_local_micro": 140000, + "advertiser_domain": null, + "target_cpa_local_micro": null, + "primary_web_event_tag": null, + "goal": "ENGAGEMENT", + "daily_budget_amount_local_micro": null, + "product_type": "PROMOTED_TWEETS", + "end_time": null, + "bid_strategy": "MAX", + "duration_in_days": null, + "standard_delivery": null, + "total_budget_amount_local_micro": null, + "objective": "ENGAGEMENTS", + "id": "9cqi0", + "entity_status": "PAUSED", + "automatic_tweet_promotion": null, + "frequency_cap": null, + "android_app_store_identifier": null, + "categories": [], + "currency": "USD", + "pay_by": "ENGAGEMENT", + "created_at": "2017-07-07T17:42:20Z", + "ios_app_store_identifier": null, + "updated_at": "2022-06-03T23:51:36Z", + "campaign_id": "8yn7m", + "creative_source": "MANUAL", + "deleted": false + } + } +``` + +#### DELETE accounts/:account\_id/line\_items/:line\_item\_id[](#delete-accounts-account-id-line-items-line-item-id "Permalink to this headline") + +Delete the specified line item belonging to the current account. + +**Note**: Deleting a line item is not reversible and subsequent attempts to delete the resource will return HTTP 404. + +**Note**: When a line item is deleted, its child promoted\_tweets are only returned in the GET accounts/:account\_id/promoted\_tweets and GET accounts/:account\_id/promoted\_tweets/:promoted\_tweet_id endpoints if `with_deleted=true` is specified in the request. These promoted_tweets are not actually deleted, though (`"deleted": false` in the response). We do not cascade deletes. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Exampple: `9f2ix` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "bid_strategy": "MAX", + "advertiser_user_id": "756201191646691328", + "name": "Untitled", + "placements": [], + "start_time": null, + "bid_amount_local_micro": 100000, + "advertiser_domain": null, + "target_cpa_local_micro": null, + "primary_web_event_tag": null, + "pay_by": "ENGAGEMENT", + "product_type": "PROMOTED_TWEETS", + "end_time": "2017-07-21T00:00:00Z", + "duration_in_days": 1, + "total_budget_amount_local_micro": null, + "objective": "ENGAGEMENTS", + "id": "9f2ix", + "entity_status": "ACTIVE", + "goal": "ENGAGEMENT", + "frequency_cap": 5, + "categories": [], + "currency": "USD", + "created_at": "2017-07-14T00:01:50Z", + "updated_at": "2017-08-09T07:41:08Z", + "campaign_id": "90r8n", + "creative_source": "MANUAL", + "deleted": true + }, + "request": { + "params": { + "line_item_id": "9f2ix", + "account_id": "18ce54d4x5t" + } + } + } +``` +### Line Item Curated Categories + + +Additional details on usage can be found at the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective) + +#### GET accounts/:account\_id/line\_item\_curated\_categories[](#get-accounts-account-id-line-item-curated-categories "Permalink to this headline") + +Retrieve details for some or all line item curated categories associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories` + +**Example Response[](#example-response "Permalink to this headline")** + +```josn + { + "request": { + "params": { + "account_id": "abc1" + } + }, + "next_cursor": null, + "data": [ + { + "line_item_id": "by5pw", + "curated_category_id": "7op29tp2jzeo", + "id": "1", + "created_at": "2018-06-29T04:19:53Z", + "updated_at": "2018-06-29T04:19:53Z", + "deleted": false + } + ] + } +``` + +#### GET accounts/:account\_id/line\_item\_curated\_categories/:line\_item\_curated\_category\_id[](#get-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline") + +Retrieves details for a specific line item curated category associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_curated\_category\_id
_required_ | A reference to the line item curated category you are operating with in the request.

Type: string

Example: `43853bhii885` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "line_item_curated_category_id": "yav", + "account_id": "abc1" + } + }, + "data": { + "line_item_id": "by5pw", + "curated_category_id": "7op29tp2jzeo", + "id": "yav", + "created_at": "2018-06-29T04:19:53Z", + "updated_at": "2018-06-29T04:19:53Z", + "deleted": false + } + } +``` + +#### POST accounts/:account\_id/line\_item\_curated\_categories[](#post-accounts-account-id-line-item-curated-categories "Permalink to this headline") + +Associate a [curated category](/x-ads-api/campaign-management/reference#curated-categories-2) object with the specified line item. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| curated\_category\_id
`required` | A reference to the curated category entity you are operating with in the request.

Type: string

Example: `10miy` | +| line\_item\_id
`required` | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "curated_category_id": "9ddrgesiap6o", + "line_item_id": "iqwka", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "iqwka", + "curated_category_id": "9ddrgesiap6o", + "id": "xq", + "created_at": "2021-03-30T17:26:42Z", + "updated_at": "2021-03-30T17:26:42Z", + "deleted": false + } + } +``` + +#### PUT accounts/:account\_id/line\_item\_curated\_categories/:line\_item\_curated\_category\_id[](#put-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline") + +Update the specified line item curated category. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_curated\_category\_id
_required_ | A reference to the line item curated category you are operating with in the request.

Type: string

Example: `1bzq3` | +| curated\_category\_id
`optional` | A reference to the curated category entity you are operating with in the request.

Type: string

Example: `10miy` | +| line\_item\_id
`optional` | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | + +**Example Request[](#example-request "Permalink to this headline")** + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "line_item_curated_category_id": "xq", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "iqwka", + "curated_category_id": "8tujl1p3yn0g", + "id": "xq", + "created_at": "2021-03-30T17:26:42Z", + "updated_at": "2021-03-30T18:22:52Z", + "deleted": true + } + } +``` + +#### DELETE accounts/:account\_id/line\_item\_curated\_categories/:line\_item\_curated\_category\_id[](#delete-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline") + +Delete the specified line item curated category. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_curated\_category\_id
_required_ | A reference to the line item curated category you are operating with in the request.

Type: string

Example: `1bzq3` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "line_item_curated_category_id": "xq", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "iqwka", + "curated_category_id": "9ddrgesiap6o", + "id": "xq", + "created_at": "2021-03-30T17:26:42Z", + "updated_at": "2021-03-30T18:22:52Z", + "deleted": true + } + } +``` +### Line Item Placements + + +#### GET line_items/placements[](#get-line-items-placements "Permalink to this headline") + +Retrieve valid `placement` and `product_type` combinations. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/line_items/placements` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| product_type
_optional_ | Scope the response to just the valid placements for the specified product type.

Type: enum

Possible values: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "product_type": "PROMOTED_ACCOUNT", + "placements": [ + [ + "ALL_ON_TWITTER" + ], + [ + "TWITTER_TIMELINE" + ] + ] + } + ], + "request": { + "params": { + "product_type": "PROMOTED_ACCOUNT" + } + } + } +``` +### Media Creatives + + +#### GET accounts/:account\_id/media\_creatives[](#get-accounts-account-id-media-creatives "Permalink to this headline") + +Retrieve details for some or all media creatives associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/media_creatives` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| campaign_id
_optional_ | Scope the response to just the media creatives associated with the specified campaign.

Type: string

Example: `8gdx6` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| line\_item\_ids
_optional_ | Scope the response to just the media creatives associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8v7jo` | +| media\_creative\_ids
_optional_ | Scope the response to just the desired media creatives by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `1bzq3` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "media_creative_ids": [ + "1bzq3" + ] + } + }, + "next_cursor": null, + "data": [ + { + "line_item_id": "8v7jo", + "landing_url": "https://dev.x.com", + "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", + "id": "1bzq3", + "entity_status": "ACTIVE", + "created_at": "2017-07-05T06:00:42Z", + "account_media_id": "10miy", + "updated_at": "2019-01-11T20:21:26Z", + "approval_status": "ACCEPTED", + "deleted": false + } + ] + } +``` + +#### GET accounts/:account\_id/media\_creatives/:media\_creative\_id[](#get-accounts-account-id-media-creatives-media-creative-id "Permalink to this headline") + +Retrieves details for a specific media creative associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| media\_creative\_id
_required_ | A reference to the media creative you are operating with in the request.

Type: string

Example: `43853bhii885` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "media_creative_id": "1bzq3", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "8v7jo", + "landing_url": "https://dev.x.com", + "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", + "id": "1bzq3", + "entity_status": "ACTIVE", + "created_at": "2017-07-05T06:00:42Z", + "account_media_id": "10miy", + "updated_at": "2019-01-11T20:21:26Z", + "approval_status": "ACCEPTED", + "deleted": false + } + } +``` + +#### POST accounts/:account\_id/media\_creatives[](#post-accounts-account-id-media-creatives "Permalink to this headline") + +Associate an [account media](/x-ads-api/creatives#account-media) object with the specified line item. + +Use this endpoint to promote in-stream ads (when the account media `creative_type` is `PREROLL`) or image ads (such as `BANNER` or `INTERSTITIAL`) on the Twitter Audience Platform. + +**Note**: In order to add media assets to the Account Media resource, use the [POST accounts/:account\_id/media\_library](/x-ads-api/creatives#account-media) endpoint. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/media_creatives` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| account\_media\_id
`required` | A reference to the account media entity you are operating with in the request.

Type: string

Example: `10miy` | +| line\_item\_id
`required` | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | +| landing_url
`sometimes required` | The URL of the website to direct a user to. This should only be used with TAP images (or "display creatives"). This value will be ignored if used with preroll assets. To associate a URL with a preroll asset, use the [POST accounts/:account\_id/preroll\_call\_to\_actions](/x-ads-api/creatives#post-accounts-account-id-preroll-call-to-actions) endpoint.

**Note**: Required when the line item's objective is set to `WEBSITE_CLICKS`.

Type: string

Example: `https://blog.x.com/` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "line_item_id": "8v7jo", + "account_media_id": "10miy", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "8v7jo", + "landing_url": "https://dev.x.com", + "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", + "id": "1bzq3", + "entity_status": "ACTIVE", + "created_at": "2017-07-05T06:00:42Z", + "account_media_id": "10miy", + "updated_at": "2019-01-11T20:21:26Z", + "approval_status": "ACCEPTED", + "deleted": false + } + } +``` + +#### DELETE accounts/:account\_id/media\_creatives/:media\_creative\_id[](#delete-accounts-account-id-media-creatives-media-creative-id "Permalink to this headline") + +Delete the specified media creative belonging to the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| media\_creative\_id
_required_ | A reference to the media creative you are operating with in the request.

Type: string

Example: `1bzq3` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "media_creative_id": "1bzq3", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "8v7jo", + "landing_url": "https://dev.x.com", + "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", + "id": "1bzq3", + "entity_status": "ACTIVE", + "created_at": "2017-07-05T06:00:42Z", + "account_media_id": "10miy", + "updated_at": "2021-04-16T21:02:55Z", + "approval_status": "ACCEPTED", + "deleted": true + } + } +``` +### Promoted Accounts + + +#### GET accounts/:account\_id/promoted\_accounts[](#get-accounts-account-id-promoted-accounts "Permalink to this headline") + +Retrieve details for some or all promoted accounts associated with one or more line items under the current account. + +Use [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) to obtain user data for the user accounts identified by `user_id` in the response. + +An HTTP 400 will be returned if none of the specified line items are configured to contain promoted accounts. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promoted_accounts` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| line\_item\_ids
_optional_ | Scope the response to just the promoted accounts associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `9bpb2` | +| promoted\_account\_ids
_optional_ | Scope the response to just the desired promoted accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `19pl2` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2` + +**Example Response[](#example-response "Permalink to this headline")** + +```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 accounts/:account\_id/promoted\_accounts/:promoted\_account\_id[](#get-accounts-account-id-promoted-accounts-promoted-account-id "Permalink to this headline") + +Retrieve a specific reference to an account associated with a line item under the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| promoted\_account\_id
_required_ | A reference to the promoted account you are operating with in the request.

Type: string

Example: `19pl2` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "promoted_account_id": "19pl2", + "account_id": "18ce54d4x5t" + } + }, + "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 + } + } +``` + +#### POST accounts/:account\_id/promoted\_accounts[](#post-accounts-account-id-promoted-accounts "Permalink to this headline") + +Associate an account (`user_id`) with the specified line item. + +If the specified line item is not configured to be associated with Promoted Accounts, a HTTP 400 `INCOMPATIBLE_LINE_ITEM` error will be returned. If the specified user is ineligible for promotion, a HTTP 400 will be returned and no users will be promoted. If the provided user is already promoted, the request will be ignored. + +For more information on Promoted Accounts, see our [campaign management](/x-ads-api/campaign-management/reference#advertiser-api) page. + +**Note**: It is not possible to update (PUT) promoted accounts entities. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promoted_accounts` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `9bpb2` | +| user_id
_required_ | A reference to the user you are operating with in the request. Use [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) to retrieve a user ID for a screen name.

Type: long

Example: `756201191646691328` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "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 + }, + "request": { + "params": { + "user_id": "756201191646691328", + "line_item_id": "9bpb2", + "account_id": "18ce54d4x5t" + } + } + } +``` + +#### DELETE accounts/:account\_id/promoted\_accounts/:promoted\_account\_id[](#delete-accounts-account-id-promoted-accounts-promoted-account-id "Permalink to this headline") + +Disassociate an account from the specified line item. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| promoted\_account\_id
_required_ | The identifier refers to the instance of a Promoted Account associated with a line item.

Type: string

Example: `19pl2` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "line_item_id": "9bpb2", + "user_id": "756201191646691328", + "id": "19pl2", + "entity_status": "ACTIVE", + "created_at": "2017-07-05T05:54:13Z", + "updated_at": "2017-08-23T18:53:15Z", + "approval_status": "ACCEPTED", + "deleted": true + }, + "request": { + "params": { + "promoted_account_id": "19pl2", + "account_id": "18ce54d4x5t" + } + } + } +``` +### Promoted Tweets + + +#### GET accounts/:account\_id/promoted\_tweets[](#get-accounts-account-id-promoted-tweets "Permalink to this headline") + +Retrieve references to Tweets associated with line items under the current account. + +Use the [GET accounts/:account_id/tweets](/x-ads-api/creatives#get-accounts-account-id-tweets) endpoint to fetch the Tweet objects. Use the `tweet_id` values for each promoted_tweets object. + +**Note**: When parent line items are deleted, promoted_tweets are only returned if `with_deleted=true` is specified in the request. These promoted_tweets are not actually deleted, though (`"deleted": false` in the response). + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promoted_tweets` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| line\_item\_ids
_optional_ | Scope the response to just the Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `96uzp` | +| promoted\_tweet\_ids
_optional_ | Scope the response to just the desired promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `1efwlo` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "promoted_tweet_ids": [ + "1efwlo" + ], + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "line_item_id": "96uzp", + "id": "1efwlo", + "entity_status": "ACTIVE", + "created_at": "2017-06-29T05:06:57Z", + "updated_at": "2017-06-29T05:08:46Z", + "approval_status": "ACCEPTED", + "tweet_id": "880290790664060928", + "deleted": false + } + ] + } +``` + +#### GET accounts/:account\_id/promoted\_tweets/:promoted\_tweet\_id[](#get-accounts-account-id-promoted-tweets-promoted-tweet-id "Permalink to this headline") + +Retrieve a specific reference to a Tweet associated with a line item under the current account. + +**Note**: When parent line items are deleted, promoted_tweets are only returned if `with_deleted=true` is specified in the request. These promoted_tweets are not actually deleted, though (`"deleted": false` in the response). + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| promoted\_tweet\_id
_required_ | A reference to the promoted Tweet you are operating with in the request.

Type: string

Example: `1efwlo` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "promoted_tweet_id": "1efwlo", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "96uzp", + "id": "1efwlo", + "entity_status": "ACTIVE", + "created_at": "2017-06-29T05:06:57Z", + "updated_at": "2017-06-29T05:08:46Z", + "approval_status": "ACCEPTED", + "tweet_id": "880290790664060928", + "deleted": false + } + } +``` + +#### POST accounts/:account\_id/promoted\_tweets[](#post-accounts-account-id-promoted-tweets "Permalink to this headline") + +Associate one or more Tweets with the specified line item. Not all Tweets are appropriate for promotion, depending on the campaign objective. Please see [Objective-based Campaigns](/x-ads-api/campaign-management/reference#objective-based-campaigns) for more information. + +When using the `PROMOTED_ACCOUNT` product type, associating a Tweet with the `line_item` will add timeline placements on mobile in addition to the standard `PROMOTED_ACCOUNT` placement. + +**Note**: It is not possible to update (PUT) promoted Tweet entities. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promoted_tweets` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | +| tweet_ids
_required_ | A comma-separated list of identifiers corresponding to specific Tweets. Up to 50 IDs may be provided.

Type: long

Example: `822333526255120384` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "line_item_id": "8v7jo", + "id": "1e8i2k", + "entity_status": "ACTIVE", + "created_at": "2017-06-24T04:21:36Z", + "updated_at": "2017-06-24T04:21:36Z", + "approval_status": "ACCEPTED", + "tweet_id": "822333526255120384", + "deleted": false + } + ], + "request": { + "params": { + "line_item_id": "8v7jo", + "tweet_ids": [ + 822333526255120384 + ], + "account_id": "18ce54d4x5t" + } + }, + "total_count": 1 + } +``` + +#### DELETE accounts/:account\_id/promoted\_tweets/:promoted\_tweet\_id[](#delete-accounts-account-id-promoted-tweets-promoted-tweet-id "Permalink to this headline") + +Disassociate a Tweet from the specified line item. + +**Note**: A deleted promoted_tweets entity will be displayed as "Paused" in the ads.x.com UI. Similarly, "pausing" from the UI will disassociate the Tweet from its line item. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| promoted\_tweet\_id
_required_ | The identifier refers to the instance of a Promoted Tweet associated with a line item. This comes from the `id` field from a response item to [GET accounts/:account\_id/promoted\_tweets](#get-accounts-account-id-promoted-tweets), not the `tweet_id` of the Tweet in question. Supplied within the resource's path.

Type: string

Example: `1gp8a5` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "line_item_id": "9pl99", + "id": "1gp8a5", + "entity_status": "ACTIVE", + "created_at": "2017-08-17T17:02:21Z", + "updated_at": "2017-08-18T06:43:48Z", + "approval_status": "ACCEPTED", + "tweet_id": "844796297743757315", + "deleted": true + }, + "request": { + "params": { + "promoted_tweet_id": "1gp8a5", + "account_id": "18ce54d4x5t" + } + } + } +``` +### Promotable Users + + +#### GET accounts/:account\_id/promotable\_users[](#get-accounts-account-id-promotable-users "Permalink to this headline") + +Retrieve details for some or all promotable users associated with the current account. + +The promotable user type is either `FULL` or `RETWEETS_ONLY`. This controls the type of content that is allowed to be promoted by the account. Advertisers must obtain permission to promote another user's content and contact Twitter to get them added to your account as a `RETWEETS_ONLY` promotable user. + +Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you'd like to promote. You can use the [POST accounts/:account_id/promoted-tweets](/x-ads-api/campaign-management/reference#promoted-tweets) endpoint to promote published Tweets and the [POST accounts/:account_id/scheduled-promoted-tweets](/x-ads-api/campaign-management/reference#promoted-tweets) endpoint to promote another Twitter Ads account's Scheduled Tweets. + +You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the `tweet_id` that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The `tweet_id` that is returned corresponds to this new Tweet. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promotable_users` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| promotable\_user\_ids
_optional_ | Scope the response to just the desired promotable users by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `l310s` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s` + +**Example Response[](#example-response "Permalink to this headline")** + +```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" + } + ] + } +``` + +#### GET accounts/:account\_id/promotable\_users/:promotable\_user\_id[](#get-accounts-account-id-promotable-users-promotable-user-id "Permalink to this headline") + +Retrieve a specific promotable user associated with the current account. + +The promotable user type is either `FULL` or `RETWEETS_ONLY`. This controls the type of content that is allowed to be promoted by the account. + +Advertisers must obtain permission to promote another user's content. Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you'd like to promote. + +You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the `tweet_id` that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The `tweet_id` that is returned corresponds to this new Tweet. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/promotable_users/:promotable_user_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| promotable\_user\_id
_optional_ | A reference to the promotable user you are operating on within the request

Type: string

Example: `l310s` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "promotable_user_id": "l310s", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "user_id": "2417045708", + "id": "l310s", + "created_at": "2017-03-10T17:51:24Z", + "updated_at": "2017-03-10T17:51:24Z", + "deleted": false, + "promotable_user_type": "RETWEETS_ONLY" + } + } +``` +### Publishers + + +#### GET publishers[](#get-publishers "Permalink to this headline") + +Retrieve a list of Content Category publishers' details + +Additional details can be found in the [Video Views Preroll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective) + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/publishers` + +**Parameters[](#parameters "Permalink to this headline")** + +No request parameters + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/publishers` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": {} + }, + "next_cursor": null, + "data": [ + { + "monetizable_country_codes": [ + "US" + ], + "promotion_eligible_country_codes": [ + "US" + ], + "username": "PeoplesSports", + "user_id": "1353868435021721602", + "monetization_restricted": true, + "content_category_ids": [ + "se" + ] + }, + { + "monetizable_country_codes": [ + "JP" + ], + "promotion_eligible_country_codes": [ + "JP" + ], + "username": "NewYork_Jack", + "user_id": "1331177123436851206", + "monetization_restricted": true, + "content_category_ids": [ + "sk" + ] + }, + { + "monetizable_country_codes": [ + "JP" + ], + "promotion_eligible_country_codes": [ + "JP" + ], + "username": "twispatv", + "user_id": "1331165719128461314", + "monetization_restricted": true, + "content_category_ids": [ + "sm" + ] + }, + { + "monetizable_country_codes": [ + "US" + ], + "promotion_eligible_country_codes": [ + "US" + ], + "username": "LAThieves", + "user_id": "1316808678897455105", + "monetization_restricted": true, + "content_category_ids": [ + "s0" + ] + }, + { + "monetizable_country_codes": [ + "US" + ], + "promotion_eligible_country_codes": [ + "US" + ], + "username": "Quicktake_EE", + "user_id": "1305900477427724290", + "monetization_restricted": true, + "content_category_ids": [ + "sr" + ] + }, + { + "monetizable_country_codes": [ + "BR" + ], + "promotion_eligible_country_codes": [ + "BR" + ], + "username": "eufloribella", + "user_id": "1300812459054436354", + "monetization_restricted": true, + "content_category_ids": [ + "sm" + ] + }, + { + "monetizable_country_codes": [ + "EG" + ], + "promotion_eligible_country_codes": [ + "KW", + "EG", + "SA", + "AE", + "LB", + "QA" + ], + "username": "Egypt2021EN", + "user_id": "1296077573399678977", + "monetization_restricted": true, + "content_category_ids": [ + "se" + ] + }, + { + "monetizable_country_codes": [ + "US" + ], + "promotion_eligible_country_codes": [ + "US" + ], + "username": "ClubShayShay", + "user_id": "1283068366706454529", + "monetization_restricted": true, + "content_category_ids": [ + "se" + ] + }, + { + "monetizable_country_codes": [ + "IN", + "KW", + "ID", + "EG", + "SG", + "TH", + "MY", + "PH", + "ES", + "US", + "AU", + "SA", + "AE", + "LB", + "GB", + "FR", + "KR", + "BR", + "MX", + "QA", + "CA", + "JP" + ], + "promotion_eligible_country_codes": [ + "KW", + "EG", + "SA", + "AE", + "LB", + "QA" + ], + "username": "hiaahsanshow", + "user_id": "1253421442143641601", + "monetization_restricted": false, + "content_category_ids": [ + "sh" + ] + }, + { + "monetizable_country_codes": [ + "TH" + ], + "promotion_eligible_country_codes": [ + "TH" + ], + "username": "HoneKrasae", + "user_id": "1240684293719904256", + "monetization_restricted": true, + "content_category_ids": [ + "sr" + ] + }, + { + "monetizable_country_codes": [ + "US" + ], + "promotion_eligible_country_codes": [ + "US" + ], + "username": "Sportskind", + "user_id": "1232708694418300930", + "monetization_restricted": true, + "content_category_ids": [ + "se" + ] + }, + { + "monetizable_country_codes": [ + "IN", + "KW", + "ID", + "EG", + "SG", + "TH", + "MY", + "PH", + "ES", + "US", + "AU", + "SA", + "AE", + "LB", + "GB", + "FR", + "KR", + "BR", + "MX", + "QA", + "CA", + "JP" + ], + "promotion_eligible_country_codes": [ + "KW", + "EG", + "SA", + "AE", + "LB", + "QA" + ], + "username": "almeerathShow", + "user_id": "1229410512762437633", + "monetization_restricted": false, + "content_category_ids": [ + "sh" + ] + }, + { + "monetizable_country_codes": [ + "US" + ], + "promotion_eligible_country_codes": [ + "US" + ], + "username": "SeeYourVoiceFOX", + "user_id": "1225490734653947904", + "monetization_restricted": true, + "content_category_ids": [ + "sh" + ] + }, + { + "monetizable_country_codes": [ + "IN", + "KW", + "ID", + "EG", + "SG", + "TH", + "MY", + "PH", + "ES", + "US", + "AU", + "SA", + "AE", + "LB", + "GB", + "FR", + "KR", + "BR", + "MX", + "QA", + "CA", + "JP" + ], + "promotion_eligible_country_codes": [ + "US" + ], + "username": "AUProSports", + "user_id": "1219303449768185859", + "monetization_restricted": false, + "content_category_ids": [ + "se" + ] + } + ] + } +``` +### Recommendations + + +#### GET accounts/:account_id/recommendations[](#get-accounts-account-id-recommendations "Permalink to this headline") + +Status: _Closed Beta_ + +Retrieve campaign recommendations associated with this ads account. Currently there is a limit of 1 recommendation per funding instrument. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/5/accounts/:account_id/recommendations` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + "request": { + "params": { + "account_id": "18ce54d4x5t" + } + }, + "total_count": 1, + "data": [ + { + "funding_instrument_id": "gpvzb", + "id": "62ce8zza1q0w", + "account_id": "18ce54d4x5t", + "status": "PENDING", + "message": "Recommendation for testing", + "created_at": "2016-11-14T23:07:54Z", + "updated_at": "2016-11-14T23:07:54Z" + } + ] +``` + +#### GET accounts/:account\_id/recommendations/:recommendation\_id[](#get-accounts-account-id-recommendations-recommendation-id "Permalink to this headline") + +Status: _Closed Beta_ + +Retrieve a specific campaign recommendation associated with this ads account. + +The campaign recommendation contains a full set of changes suggested for the campaign structure represented as an object tree. The response tree is intended to work in conjunction with the Batch API endpoints, but it can also be mapped to single update endpoints as appropriate (Create for POST, Update for PUT, Delete for DELETE). + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| recommendation_id
_required_ | A reference to the recommendation ID you are operating within the request

Type: string

Example: `62ce8zza1q0w` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "recommendation_id": "62ce8zza1q0w", + "account_id": "18ce54d4x5t" + } + }, + "data_type": "recommendations", + "data": { + "changes": [ + { + "entity_type": "campaigns", + "params": { + "start_time": "2016-11-08T22:00:00Z", + "daily_budget_amount_local_micro": 2200000, + "end_time": "2016-11-16T07:59:00Z", + "total_budget_amount_local_micro": 12000000, + "id": "64m0d" + }, + "operation_type": "Update", + "dependent_entities": [ + { + "entity_type": "line_items", + "params": { + "name": "Campaign for recommendations", + "placements": [ + "TWITTER_TIMELINE" + ], + "bid_amount_local_micro": 1430000, + "id": "6f5kq", + "include_sentiment": "ALL" + }, + "operation_type": "Update", + "dependent_entities": [ + { + "entity_type": "targeting_criteria", + "params": { + "id": "a8po6p" + }, + "operation_type": null, + "dependent_entities": [] + }, + { + "entity_type": "targeting_criteria", + "params": { + "line_item_id": "6f5kq", + "name": "election results", + "targeting_value": "election results", + "targeting_type": "PHRASE_KEYWORD" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "promoted_tweets", + "params": { + "id": "101ftp" + }, + "operation_type": "Delete", + "dependent_entities": [] + }, + { + "entity_type": "targeting_criteria", + "params": { + "line_item_id": "6f5kq", + "name": "Male", + "targeting_value": 1, + "targeting_type": "GENDER" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "targeting_criteria", + "params": { + "line_item_id": "6f5kq", + "name": "San Francisco-Oakland-San Jose CA, US", + "targeting_value": "", + "targeting_type": "LOCATION" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "promoted_tweets", + "params": { + "id": "101fto" + }, + "operation_type": "Delete", + "dependent_entities": [] + }, + { + "entity_type": "promoted_tweets", + "params": { + "line_item_id": "6f5kq", + "display_properties": [], + "paused": false, + "approval_status": "ACCEPTED", + "tweet_id": "91125952589766656" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "targeting_criteria", + "params": { + "line_item_id": "6f5kq", + "name": "Partner audience targeting", + "targeting_value": "v2cx", + "targeting_type": "NEGATIVE_BEHAVIOR" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "targeting_criteria", + "params": { + "line_item_id": "6f5kq", + "name": "AGE_21_TO_34", + "targeting_value": "AGE_21_TO_34", + "targeting_type": "AGE" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "targeting_criteria", + "params": { + "id": "a8po6o" + }, + "operation_type": "Delete", + "dependent_entities": [] + }, + { + "entity_type": "promoted_tweets", + "params": { + "line_item_id": "6f5kq", + "display_properties": [], + "paused": false, + "approval_status": "ACCEPTED", + "tweet_id": "991101965843460096" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "promoted_tweets", + "params": { + "line_item_id": "6f5kq", + "display_properties": [], + "paused": false, + "approval_status": "ACCEPTED", + "tweet_id": "991127212156096516" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "targeting_criteria", + "params": { + "line_item_id": "6f5kq", + "name": "debate", + "targeting_value": "debate", + "targeting_type": "NEGATIVE_PHRASE_KEYWORD" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "targeting_criteria", + "params": { + "line_item_id": "6f5kq", + "name": "60004, IL, US", + "targeting_value": "", + "targeting_type": "LOCATION" + }, + "operation_type": "Create", + "dependent_entities": [] + }, + { + "entity_type": "targeting_criteria", + "params": { + "id": "a8po6n" + }, + "operation_type": null, + "dependent_entities": [] + }, + { + "entity_type": "promoted_tweets", + "params": { + "id": "101ftn" + }, + "operation_type": null, + "dependent_entities": [] + } + ] + } + ] + } + ], + "funding_instrument_id": "gpvzb", + "id": "62ce8zza1q0w", + "account_id": "18ce54d4x5t", + "status": "PENDING", + "message": "Recommendation for testing", + "created_at": "2016-11-14T23:07:54Z", + "updated_at": "2016-11-14T23:07:54Z" + } + } +``` +### Scheduled Promoted Tweets + + +#### GET accounts/:account\_id/scheduled\_promoted_tweets[](#get-accounts-account-id-scheduled-promoted-tweets "Permalink to this headline") + +Retrieve details for some or all scheduled promoted Tweets associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| line\_item\_ids
_optional_ | Scope the response to just the scheduled Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8xdpe` | +| scheduled\_promoted\_tweet_ids
_optional_ | Scope the response to just the desired scheduled promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `1xboq` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "scheduled_promoted_tweet_ids": [ + "1xboq" + ], + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "line_item_id": "8xdpe", + "id": "1xboq", + "created_at": "2017-06-01T19:53:32Z", + "updated_at": "2017-06-01T20:00:06Z", + "scheduled_tweet_id": "870366669373194240", + "tweet_id": "870369382207070208", + "deleted": false + } + ] + } +``` + +#### GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id[](#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id "Permalink to this headline") + +Retrieve a specific scheduled promoted Tweet associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| scheduled\_promoted\_tweet_id
_required_ | A reference to the scheduled promoted Tweet you are operating with in the request.

Type: string

Example: `1xboq` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "scheduled_promoted_tweet_id": "1xboq", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "8xdpe", + "id": "1xboq", + "created_at": "2017-06-01T19:53:32Z", + "updated_at": "2017-06-01T20:00:06Z", + "scheduled_tweet_id": "870366669373194240", + "tweet_id": "870369382207070208", + "deleted": false + } + } +``` + +#### POST accounts/:account\_id/scheduled\_promoted_tweets[](#post-accounts-account-id-scheduled-promoted-tweets "Permalink to this headline") + +Associate a scheduled Tweet with the specified line item. + +**Note**: It is not possible to update (PUT) scheduled promoted Tweet entities. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8xdpe` | +| scheduled\_tweet\_id
_required_ | A reference to the scheduled Tweet you are operating with in the request.

Type: long

Example: `870358555227860992` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "line_item_id": "8xdpe", + "id": "1xtfl", + "created_at": "2017-06-08T07:25:26Z", + "updated_at": "2017-06-08T07:25:26Z", + "scheduled_tweet_id": "870358555227860992", + "tweet_id": null, + "deleted": false + }, + "request": { + "params": { + "line_item_id": "8xdpe", + "scheduled_tweet_id": 870358555227860992, + "account_id": "18ce54d4x5t" + } + } + } +``` + +#### DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id[](#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id "Permalink to this headline") + +Disassociate a scheduled Tweet from the specified line item. + +**Note**: `scheduled_promoted_tweets` can only be deleted _before_ the scheduled Tweet's `scheduled_at` time. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| scheduled\_promoted\_tweet_id
_required_ | A reference to the scheduled promoted Tweet you are operating with in the request. This is the `id` attribute from a [GET accounts/:account\_id/scheduled\_promoted_tweets](#get-accounts-account-id-scheduled-promoted-tweets) response object.

Type: string

Example: `1xtfl` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "line_item_id": "8xdpe", + "id": "1xtfl", + "created_at": "2017-06-08T07:25:26Z", + "updated_at": "2017-06-15T05:14:12Z", + "scheduled_tweet_id": "870358555227860992", + "tweet_id": null, + "deleted": true + }, + "request": { + "params": { + "scheduled_promoted_tweet_id": "1xtfl", + "account_id": "18ce54d4x5t" + } + } + } +``` +### Targeting Criteria + + +#### GET accounts/:account\_id/targeting\_criteria[](#get-accounts-account-id-targeting-criteria "Permalink to this headline") + +Retrieve details for some or all of the targeting criteria associated with line items under the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/targeting_criteria` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_ids
_required_ | Scope the response to just the targeting criteria under the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `8u94t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| lang
_optional_ | An [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional `localized_name` attribute will be returned in the response for objects where a localized name is available.

Type: string

Example: `fr` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.

Type: string

Example: `created_at-asc` | +| targeting\_criterion\_ids
_optional_ | Scope the response to just the desired targeting criteria by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `dpl3a6` | +| 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "line_item_ids": [ + "8u94t" + ] + } + }, + "next_cursor": null, + "data": [ + { + "line_item_id": "8u94t", + "name": "Custom audience targeting", + "id": "dpl3a6", + "operator_type": "EQ", + "created_at": "2017-05-26T03:29:35Z", + "targeting_value": "249yj", + "updated_at": "2017-05-26T03:29:35Z", + "deleted": false, + "targeting_type": "CUSTOM_AUDIENCE" + } + ] + } +``` + +#### GET accounts/:account\_id/targeting\_criteria/:targeting\_criterion\_id[](#get-accounts-account-id-targeting-criteria-targeting-criterion-id "Permalink to this headline") + +Retrieve a specific targeting criterion associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| targeting\_criterion\_id
_required_ | A reference to the targeting criterion you are operating with in the request.

Type: string

Example: `eijd4y` | +| lang
_optional_ | An [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional `localized_name` attribute will be returned in the response for objects where a localized name is available.

Type: string

Example: `fr` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "targeting_criterion_id": "eijd4y", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "619jl", + "name": "🤖", + "id": "eijd4y", + "created_at": "2017-07-06T16:51:04Z", + "targeting_value": "🤖", + "updated_at": "2017-07-06T16:51:04Z", + "deleted": false, + "targeting_type": "BROAD_KEYWORD" + } + } +``` + +#### POST accounts/:account\_id/targeting\_criteria[](#post-accounts-account-id-targeting-criteria "Permalink to this headline") + +See the [Targeting Options](/x-ads-api/campaign-management/reference#targeting-options) page to find `targeting_value`s for specific targeting types. We recommend that you refresh all data weekly, to ensure that you are working with the latest set of targeting type values. We change values and available targeting criteria from time to time; while the majority of these don't change often, some do. There is no guarantee that these values will not change. + +Use the `BROAD_KEYWORD`, `EXACT_KEYWORD`, `PHRASE_KEYWORD`, or `UNORDERED_KEYWORD` targeting types with the keywords specified in the `targeting_value`. Exclude keywords by using the `operator_type` request parameter set to `NE`. See [targeting keyword types](/x-ads-api/campaign-management/reference#targeting) for a detailed description of each type. + +**Note**: It is only possible to target a single age bucket per line item. + +**Note**: To target a Custom Audience, that audience must be targetable. i.e., `targerable` _must_ equal `true`. + +**Note**: When using targeting type `TV_SHOW`, there must be at least one `LOCATION` targeting criterion on the line item prior to setting the `TV_SHOW` targeting and all `LOCATION` must be within the same locale as the `TV_SHOW` being targeted. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/targeting_criteria` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `69ob` | +| operator_type
_required_ | Specify the relationship that the targeting criterion should have. For example, to exclude keywords, use `operator_type=NE`.

Type: enum

Possible values: `EQ`, `NE`, `GTE`, `LT` | +| targeting_type
_required_ | The type of targeting that will be applied to this line item.

Possible non-keyword-based values include: `AGE`, `DEVICE`, `EVENT`, `CAMPAIGN_ENGAGEMENT`, `CAMPAIGN_ENGAGEMENT_LOOKALIKE`, `CONVERSATION`, `ENGAGEMENT_TYPE`, `FOLLOWERS_OF_USER`, `GENDER`, `INTEREST`, `LANGUAGE`, `LIVE_TV_EVENT`, `LOCATION`, `NETWORK_ACTIVATION_DURATION`, `NETWORK_OPERATOR`, `PLATFORM`, `PLATFORM_VERSION`, `SIMILAR_TO_FOLLOWERS_OF_USER`, `TV_SHOW`, `USER_ENGAGEMENT`, `USER_ENGAGEMENT_LOOKALIKE`, `WIFI_ONLY`

**Note**: It is only possible to target a single `AGE` bucket per line item.

Possible keyword-based values include: `BROAD_KEYWORD`, `EXACT_KEYWORD`, `PHRASE_KEYWORD`, `UNORDERED_KEYWORD`

Possible custom audience values include: `CUSTOM_AUDIENCE`, `CUSTOM_AUDIENCE_EXPANDED`

Possible installed app store category values: `APP_STORE_CATEGORY`, `APP_STORE_CATEGORY_LOOKALIKE`

Possible Twitter Audience Platform (TAP) app exclusion: `APP_LIST` (may only be used with `operator_type=NE`) | +| targeting_value
_required_ | Specify which user, which interest, which location, which event, which platform, which platform version, which device, which keyword or phrase, which gender, which custom audience, which app store category, or which exclusion of an app list this targeting will be applied to, depending on the selected targeting_type.

Type: string

Example: `174958347` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "line_item_id": "619jl", + "name": "technology", + "id": "fbyjlr", + "created_at": "2017-09-06T07:31:21Z", + "targeting_value": "technology", + "updated_at": "2017-09-06T07:31:21Z", + "deleted": false, + "targeting_type": "BROAD_KEYWORD" + }, + "request": { + "params": { + "line_item_id": "619jl", + "targeting_type": "BROAD_KEYWORD", + "targeting_value": "technology", + "account_id": "18ce54d4x5t" + } + } + } +``` + +#### POST batch/accounts/:account\_id/targeting\_criteria[](#post-batch-accounts-account-id-targeting-criteria "Permalink to this headline") + +Allows the batch creation of new Targeting Criteria with a single request. + +**Batch Requests** + +* The current maximum batch size is 500. +* 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 Targeting Criteria parameter) are shown in the response under the `operation_errors` object. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/batch/accounts/:account_id/targeting_criteria` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| operation_type
_required_ | The per item operation type being performed.

Type: enum

Possible values: `Create`, `Delete` | +| params
_required_ | A JSON object containing all the parameters for the targeting criteria objects. For a list of required and optional targeting criteria parameters, see [here](#post-accounts-account-id-targeting-criteria).

In addition, this endpoint supports an `operator_type` parameter that works in conjunction with certain `targeting_type` values. The possible values for this parameter are `EQ` for equal to, `GTE` for greater than or equal to, `LT` for less than, and `NE` for not equal to. | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/targeting_criteria` + +```json + [ + { + "operation_type":"Create", + "params":{ + "line_item_id":"6f9an", + "targeting_type":"LOCATION", + "targeting_value":"5122804691e5fecc" + } + }, + { + "operation_type":"Delete", + "params":{ + "targeting_criterion_id":"al2rua" + } + } + ] +``` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data_type": "targeting_criterion", + "data": [ + { + "line_item_id": "6f9an", + "name": "San Francisco-Oakland-San Jose CA, US", + "id": "al7vt2", + "location_type": "CITY", + "operator_type": "EQ", + "created_at": "2016-11-11T22:59:50Z", + "targeting_value": "5122804691e5fecc", + "updated_at": "2016-11-11T22:59:50Z", + "deleted": false, + "targeting_type": "LOCATION" + }, + { + "line_item_id": "6keuo", + "name": "accounts", + "id": "al2rua", + "operator_type": "EQ", + "created_at": "2016-11-11T17:50:19Z", + "targeting_value": "accounts", + "updated_at": "2016-11-11T22:59:50Z", + "deleted": true, + "targeting_type": "BROAD_KEYWORD" + } + ], + "request": [ + { + "params": { + "line_item_id": "6f9an", + "targeting_type": "LOCATION", + "targeting_value": "5122804691e5fecc", + "account_id": "18ce54d4x5t" + }, + "operation_type": "Create" + }, + { + "params": { + "targeting_criterion_id": "al2rua", + "account_id": "18ce54d4x5t" + }, + "operation_type": "Delete" + } + ] + } +``` + +#### DELETE accounts/:account\_id/targeting\_criteria/:targeting\_criterion\_id[](#delete-accounts-account-id-targeting-criteria-targeting-criterion-id "Permalink to this headline") + +Delete the specified targeting criterion belonging to the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| targeting\_criterion\_id
_required_ | A reference to the targeting criterion you are operating with in the request.

Type: string

Example: `dpl3a6` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": { + "line_item_id": "8u94t", + "name": "Custom audience targeting", + "id": "dpl3a6", + "created_at": "2017-05-26T03:29:35Z", + "targeting_value": "249yj", + "updated_at": "2017-08-30T18:38:58Z", + "deleted": true, + "targeting_type": "CUSTOM_AUDIENCE" + }, + "request": { + "params": { + "targeting_criterion_id": "dpl3a6", + "account_id": "18ce54d4x5t" + } + } + } +``` +### Targeting Options + + +* [App Store Categories](#get-targeting-criteria-app-store-categories) +* [Conversation](#get-targeting-criteria-conversations) +* [Devices](#get-targeting-criteria-devices) +* [Events](#get-targeting-criteria-events) +* [Interests](#get-targeting-criteria-interests) +* [Languages](#get-targeting-criteria-languages) +* [Locations](#get-targeting-criteria-locations) +* [Network Operators](#get-targeting-criteria-network-operators) +* [Platform Versions](#get-targeting-criteria-platform-versions) +* [Platforms](#get-targeting-criteria-platforms) +* [TV Markets](#get-targeting-criteria-tv-markets) +* [TV Shows](#get-targeting-criteria-tv-shows) + +#### GET targeting\_criteria/app\_store_categories[](#get-targeting-criteria-app-store-categories "Permalink to this headline") + +Discover available app store category-based targeting criteria for Promoted Products. App store categories are available for the iOS App Store and the Google Play store only. + +Installed app category targeting allows targeting of users based on the categories of apps they have installed or have indicated interest in. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/app_store_categories` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| q
_optional_ | An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: `music` | +| os_type
_optional_ | Scope the results by a specific app store.

Type: enum

Possible values: `ANDROID`, `IOS` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "name": "Games: Music", + "targeting_type": "APP_STORE_CATEGORY", + "targeting_value": "qouq", + "os_type": "IOS" + }, + { + "name": "Music", + "targeting_type": "APP_STORE_CATEGORY", + "targeting_value": "qov2", + "os_type": "IOS" + } + ], + "request": { + "params": { + "q": "music", + "os_type": "IOS" + } + } + } +``` + +#### GET targeting_criteria/conversations[](#get-targeting-criteria-conversations "Permalink to this headline") + +Discover available conversation-based targeting criteria for Promoted Products. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/conversations` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| conversation_type
_optional_ | An optional query to scope to a certain conversation type.

Type: enum

Possible values: `ACTORS`, `ATHLETES`, `BOOK_GENRES`, `BOOKS`, `BRAND_CATEGORIES`, `BRANDS`, `CELEBRITIES`, `COACHES`, `DIGITAL_CREATORS`, `ENTERTAINMENT_BRANDS`, `ENTERTAINMENT_PERSONALITIES`, `FICTIONAL_CHARACTERS`, `JOURNALISTS`, `LIFESTYLES`, `MOVIE_GENRES`, `MOVIES`, `MUSIC_GENRES`, `MUSICIANS`, `NEWS_STORIES`, `NEWS`, `PERSONS`, `PLACES`, `PODCASTS`, `POLITICAL_AFFILIATIONS`, `POLITICIANS`, `PRODUCTS`, `RADIO_STATIONS`, `SPORTS_LEAGUES`, `SPORTS_PERSONALITIES`, `SPORTS_TEAMS`, `SPORTS`, `TRENDS`, `TV_SHOWS`, `VIDEO_GAME_PLATFORMS`, `VIDEO_GAME_PUBLISHERS`, `VIDEO_GAMES` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "count": 2 + } + }, + "next_cursor": "1f7m7", + "data": [ + { + "targeting_type": "CONVERSATION", + "targeting_value": "a1", + "name": "NFL", + "conversation_type": "SPORTS" + }, + { + "targeting_type": "CONVERSATION", + "targeting_value": "a2", + "name": "NBA", + "conversation_type": "SPORTS" + } + ] + } +``` + +#### GET targeting_criteria/devices[](#get-targeting-criteria-devices "Permalink to this headline") + +Discover available device-based targeting criteria for Promoted Products. Device targeting is available for Promoted Tweets. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/devices` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | +| q
_optional_ | An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: `apple` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "name": "iPhone 3GS", + "manufacturer": "Apple", + "os_type": "iOS", + "targeting_value": "1q", + "targeting_type": "DEVICE" + }, + { + "name": "iPhone 4", + "manufacturer": "Apple", + "os_type": "iOS", + "targeting_value": "1r", + "targeting_type": "DEVICE" + } + ], + "request": { + "params": { + "q": "iphone", + "count": 2 + } + } + } +``` + +#### GET targeting_criteria/events[](#get-targeting-criteria-events "Permalink to this headline") + +Discover available event-based targeting criteria for Promoted Products. Only one event can be targeted per line item. + +**Note**: Events often exist across timezones, leading to complications when considering event times from cross-timezone perspectives. To simplify this, all event `start_time` and `end_time` values on this endpoint are represented in UTC±00:00, irrespective of the event's locale and timezone. This design should be kept in mind when querying and interacting with event `start_time` and `end_time` values. For example, Independence Day for the US is represented as `start_time=2017-07-04T00:00:00Z` and `end_time=2017-07-05T00:00:00Z` in UTC±00:00, and thus avoids the issue of this holiday existing across multiple timezones within the US. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/events` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| event_types
_required_ | An optional query to scope to certain event types.

Type: enum

Possible values: `CONFERENCE`, `HOLIDAY`, `MUSIC_AND_ENTERTAINMENT`, `OTHER`, `POLITICS`, `RECURRING`, `SPORTS` | +| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | +| country_codes
_optional_ | An optional query to scope a targeting criteria search to particular countries with the 2 letter ISO country code. If this parameter is not specified, all events are returned.

Type: string | +| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| end_time
_optional_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the campaign will end.

Type: string

Example: `2017-10-05T00:00:00Z` | +| start_time
_optional_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.

**Note**: Defaults to the current time.

Type: string

Example: `2017-07-05T00:00:00Z` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/events?count=1` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "count": 1 + } + }, + "data_type": "events", + "data": [ + { + "reach": { + "total_reach": null + }, + "name": "New Year's", + "start_time": "2017-12-31T00:00:00Z", + "top_users": [], + "top_tweets": [], + "top_hashtags": [], + "gender_breakdown_percentage": {}, + "end_time": "2018-01-02T00:00:00Z", + "country_code": null, + "device_breakdown_percentage": {}, + "targeting_value": "1ex", + "is_global": true, + "event_type": "HOLIDAY", + "country_breakdown_percentage": {} + } + ], + "next_cursor": "uww0" + } +``` + +#### GET targeting_criteria/interests[](#get-targeting-criteria-interests "Permalink to this headline") + +Discover available interest-based targeting criteria for Promoted Products. Interests change infrequently, however we suggest you refresh this list at least once weekly. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/interests` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| q
_optional_ | An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: `books` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/interests?q=books` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "name": "Books and literature/Biographies and memoirs", + "targeting_type": "INTEREST", + "targeting_value": "1001" + } + ], + "request": { + "params": { + "q": "books", + "count": 1 + } + }, + "next_cursor": "6by4n4" + } +``` + +#### GET targeting_criteria/languages[](#get-targeting-criteria-languages "Permalink to this headline") + +Discover languages available for targeting. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/languages` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| q
_optional_ | An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: `english` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/languages?q=english` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "name": "English", + "targeting_type": "LANGUAGE", + "targeting_value": "en" + } + ], + "request": { + "params": { + "q": "english" + } + }, + "next_cursor": null + } +``` + +#### GET targeting_criteria/locations[](#get-targeting-criteria-locations "Permalink to this headline") + +Discover available location-based targeting criteria for Promoted Products. Geo-targeting is available for Promoted Accounts and Promoted Tweets at the country level, state/region level, city level, and postal code level. Postal code targeting must be used if you wish to retrieve analytics at the postal code level. + +**Note**: To retrieve specific targetable cities, such as San Francisco or New York, use the `CITIES` enum with the `location_type` request parameter. + +To target Designated Market Areas (DMAs), use the `METROS` enum. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/locations` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | +| country_code
_optional_ | An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. Omit this parameter to retrieve results for all countries.

Type: string

Example: `JP` | +| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| location_type
_optional_ | Scope the results by a specific kind of location. More granular targeting than `COUNTRIES` may not be available in all locations.

Type: enum

Possible values: `COUNTRIES`, `REGIONS`, `METROS`, `CITIES`, `POSTAL_CODES` | +| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.

Type: string

Example: `New York` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "name": "Los Angeles, Los Angeles CA, CA, USA", + "country_code": "US", + "location_type": "CITIES", + "targeting_value": "3b77caf94bfc81fe", + "targeting_type": "LOCATION" + }, + { + "name": "East Los Angeles, Los Angeles CA, CA, USA", + "country_code": "US", + "location_type": "CITIES", + "targeting_value": "67571a7baaa5906b", + "targeting_type": "LOCATION" + }, + { + "name": "Lake Los Angeles, Los Angeles CA, CA, USA", + "country_code": "US", + "location_type": "CITIES", + "targeting_value": "ea9bfbd43c93400f", + "targeting_type": "LOCATION" + }, + { + "name": "Los Gatos, San Francisco-Oakland-San Jose CA, CA, USA", + "country_code": "US", + "location_type": "CITIES", + "targeting_value": "a2de7c70b82b0ca0", + "targeting_type": "LOCATION" + }, + { + "name": "Los Altos, Monterey-Salinas CA, CA, USA", + "country_code": "US", + "location_type": "CITIES", + "targeting_value": "6a4364ea6f987c10", + "targeting_type": "LOCATION" + }, + { + "name": "Los Banos, CA, USA", + "country_code": "US", + "location_type": "CITIES", + "targeting_value": "b1b6fc646de75904", + "targeting_type": "LOCATION" + }, + { + "name": "Los Alamitos, Los Angeles CA, CA, USA", + "country_code": "US", + "location_type": "CITIES", + "targeting_value": "0799ff0a3c1006e9", + "targeting_type": "LOCATION" + }, + { + "name": "Los Angeles, US", + "country_code": "US", + "location_type": "CITIES", + "targeting_value": "019940ae78c7b3bc", + "targeting_type": "LOCATION" + } + ], + "request": { + "params": { + "location_type": "CITIES", + "q": "los angeles" + } + }, + "next_cursor": null + } +``` + +#### GET targeting\_criteria/network\_operators[](#get-targeting-criteria-network-operators "Permalink to this headline") + +Discover available network operator-based targeting criteria for Promoted Products. + +This endpoint enables you to lookup targetingable carriers, such as AT&T, Verizon, Sprint, T-Mobile, etc., in multiple countries. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/network_operators` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | +| country_code
_optional_ | An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned.

Type: string

Default: `US` | +| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: `Airpeak` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "country_code": "US", + "targeting_type": "NETWORK_OPERATOR", + "name": "Advantage", + "targeting_value": "2l" + }, + { + "country_code": "US", + "targeting_type": "NETWORK_OPERATOR", + "name": "Aeris", + "targeting_value": "1b" + }, + { + "country_code": "US", + "targeting_type": "NETWORK_OPERATOR", + "name": "Airadigm", + "targeting_value": "2t" + }, + { + "country_code": "US", + "targeting_type": "NETWORK_OPERATOR", + "name": "Airlink PCS", + "targeting_value": "14" + }, + { + "country_code": "US", + "targeting_type": "NETWORK_OPERATOR", + "name": "Airpeak", + "targeting_value": "1i" + } + ], + "request": { + "params": { + "country_code": "US", + "count": 5 + } + }, + "next_cursor": "o7x9iet1a5u608olj4" + } +``` + +#### GET targeting\_criteria/platform\_versions[](#get-targeting-criteria-platform-versions "Permalink to this headline") + +Discover available mobile OS version-based targeting criteria for Promoted Products. Platform version targeting is available for Promoted Accounts and Promoted Tweets. This allows targeting down to the point release of a mobile operating system version, such as Android 8.0 or iOS 10.0. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/platform_versions` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: `jelly bean` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/platform_versions` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + {...}, + { + "name": "Ice Cream Sandwich", + "number": "4.0", + "os_type": "Android", + "targeting_type": "PLATFORM_VERSION", + "targeting_value": "17" + }, + { + "name": "Jelly Bean", + "number": "4.1", + "os_type": "Android", + "targeting_type": "PLATFORM_VERSION", + "targeting_value": "18" + }, + {...} + ], + "data_type": "targeting_criterion", + "request": { + "params": {} + } + } +``` + +#### GET targeting_criteria/platforms[](#get-targeting-criteria-platforms "Permalink to this headline") + +Discover available platform-based targeting criteria for Promoted Products. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/platforms` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `200`
Min, Max: `1`, `1000` | +| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: `ios`, `blackberry` | +| lang
_optional_ | Using a [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional localized_name attribute will be returned in the response.

Type: int, string

Example: `fr` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/platforms` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "name": "iOS", + "targeting_type": "PLATFORM", + "targeting_value": "0" + }, + { + "name": "Android", + "targeting_type": "PLATFORM", + "targeting_value": "1" + }, + { + "name": "BlackBerry phones and tablets", + "targeting_type": "PLATFORM", + "targeting_value": "2" + }, + { + "name": "Mobile web on other devices", + "targeting_type": "PLATFORM", + "targeting_value": "3" + }, + { + "name": "Desktop and laptop computers", + "targeting_type": "PLATFORM", + "targeting_value": "4" + } + ], + "request": { + "params": {} + } + } +``` + +#### GET targeting\_criteria/tv\_markets[](#get-targeting-criteria-tv-markets "Permalink to this headline") + +Discover available TV markets where TV shows can be targeted. Returns markets by locale that can used to query the [GET targeting\_criteria/tv\_shows](/x-ads-api/campaign-management/reference#get-targeting-criteria-tv-shows) endpoint. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/tv_markets` + +**Parameters[](#parameters "Permalink to this headline")** + +None + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/tv_markets` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "data": [ + { + "name": "France", + "country_code": "FR", + "locale": "fr-FR" + }, + { + "name": "Chile", + "country_code": "CL", + "locale": "es-CL" + }, + { + "name": "Germany", + "country_code": "DE", + "locale": "de-DE" + }, + { + "name": "Netherlands", + "country_code": "NL", + "locale": "nl-NL" + }, + { + "name": "United States", + "country_code": "US", + "locale": "en-US" + }, + { + "name": "Venezuela", + "country_code": "VE", + "locale": "es-VE" + }, + { + "name": "Brazil", + "country_code": "BR", + "locale": "pt-BR" + }, + { + "name": "Mexico", + "country_code": "MX", + "locale": "es-MX" + }, + { + "name": "Colombia", + "country_code": "CO", + "locale": "es-CO" + }, + { + "name": "United Kingdom", + "country_code": "GB", + "locale": "en-GB" + }, + { + "name": "Argentina", + "country_code": "AR", + "locale": "es-AR" + }, + { + "name": "Japan", + "country_code": "JP", + "locale": "ja-JP" + }, + { + "name": "Canada", + "country_code": "CA", + "locale": "en-CA" + }, + { + "name": "Spain", + "country_code": "ES", + "locale": "es-ES" + }, + { + "name": "Italy", + "country_code": "IT", + "locale": "it-IT" + }, + { + "name": "United States - Hispanic", + "country_code": "US", + "locale": "es-US" + }, + { + "name": "Ireland", + "country_code": "IE", + "locale": "en-IE" + } + ], + "request": { + "params": {} + } + } +``` + +#### GET targeting\_criteria/tv\_shows[](#get-targeting-criteria-tv-shows "Permalink to this headline") + +Discover available TV show-based targeting criteria for Promoted Products. TV show targeting is available for Promoted Tweets in certain markets. See the [GET targeting\_criteria/tv\_markets](/x-ads-api/campaign-management/reference#get-targeting-criteria-tv-markets) endpoint for available markets. + +**Note**: Any audience that contains fewer than 1,000 users will appear with an `estimated_users` value of `1000`. + +**Note**: TV channel and genre targeting options are no longer supported. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/targeting_criteria/tv_shows` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| locale
_required_ | A required parameter that specifies the tv\_market\_locale to query for available TV shows. TV markets are queried based on `locale` returned from the [GET targeting\_criteria/tv\_markets](/x-ads-api/campaign-management/reference#get-accounts-account-id-targeting-criteria).

Type: string

Example: `en-US` | +| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `50`
Min, Max: `1`, `50` | +| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| q
_optional_ | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: `ios`, `blackberry` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1` + +**Example Response[](#example-response "Permalink to this headline")** + +```jdon + { + "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" + } + } + } +``` +### Targeting Suggestions + + +#### GET accounts/:account\_id/targeting\_suggestions[](#get-accounts-account-id-targeting-suggestions "Permalink to this headline") + +Get up to 50 keyword or user targeting suggestions to complement your initial selection. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/targeting_suggestions` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticating user.

Type: string

Example: `18ce54d4x5t` | +| suggestion_type
_required_ | Specify the type of suggestions to return.

Type: enum

Possible values: `KEYWORD`, `USER_ID` | +| targeting_values
_required_ | Comma separated collection of either keywords or user IDs used to seed the suggestions.

**Note**: These two types of suggestions cannot be mixed.

Example: `756201191646691328` | +| count
_optional_ | Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: `30`
Min, Max: `1`, `50` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"` + +**Example Response[](#example-response "Permalink to this headline")** + +```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" + } + } + } +``` +### Tax Settings + + +#### GET accounts/:account\_id/tax\_settings[](#get-accounts-account-id-tax-settings "Permalink to this headline") + +Retrieve tax setting details associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/tax_settings` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t" + } + }, + "data": { + "tax_id": "GB896391250", + "address_city": "London", + "business_relationship": "SELF", + "address_street1": "21 March St", + "address_last_name": null, + "address_company": "ABC, Inc.", + "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 + } + } +``` + +#### PUT accounts/:account\_id/tax\_settings[](#put-accounts-account-id-tax-settings "Permalink to this headline") + +Update the tax settings for the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/tax_settings` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| address_city
_optional_ | The city for the account owner's address.

Type: string

Example: `San Francisco` | +| address_country
_optional_ | The two-letter country code for the account owner's address.

Type: string

Example: `US` | +| address_email
_optional_ | The email associated with the account owner's address.

Type: string

Example: `api@mctestface.com` | +| address\_first\_name
_optional_ | The first name for the account owner's address.

Type: string

Example: `API` | +| address\_last\_name
_optional_ | The last name for the account owner's address.

Type: string

Example: `McTestface` | +| address_name
_optional_ | The company name for the account owner's address.

Type: string

Example: `ABC, Co.` | +| address\_postal\_code
_optional_ | The postal code for the account owner's address.

Type: string

Example: `94102` | +| address_region
_optional_ | The region for the account owner's address.

Type: string

Example: `California` | +| address_street1
_optional_ | The street line for the account owner's address.

Type: string

Example: `21 March St` | +| address_street2
_optional_ | The second street line for the account owner's address.

Type: string

Example: `Suite 99` | +| bill_to
_optional_ | The entity that is billed.

Type: enum

Possible values: `ADVERTISER`, `AGENCY` | +| business_relationship
_optional_ | Whether the account is owned by the advertiser or by the agency.

Type: enum

Possible values: `AGENCY`, `SELF` | +| client\_address\_city
_optional_ | The city for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Toronto` | +| client\_address\_country
_optional_ | The two-letter country code for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `CA` | +| client\_address\_email
_optional_ | The email associated with the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `ads@brand.com` | +| client\_address\_first_name
_optional_ | The first name for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Brand` | +| client\_address\_last_name
_optional_ | The last name for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Advertiser` | +| client\_address\_name
_optional_ | The company name for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Brand, Inc.` | +| client\_address\_postal_code
_optional_ | The postal code for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `M5H 2N2` | +| client\_address\_region
_optional_ | The region for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `Ontario` | +| client\_address\_street1
_optional_ | The street line for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `280 Queen St W` | +| client\_address\_street2
_optional_ | The second street line for the advertiser's address.

Set this when the ads account is owned by an agency.

Type: string

Example: `The 6` | +| invoice_jurisdiction
_optional_ | Invoice jurisdiction.

Type: enum

Possible values: `LOI_SAPIN`, `NONE`, `NOT_SET` | +| tax_category
_optional_ | Whether the taxation should be individual or business.

Type: enum

Possible values: `BUSINESS_NO_VAT`, `BUSINESS_WITH_VAT`, `INDIVIDUAL` | +| tax\_exemption\_id
_optional_ | VAT exemption ID.

Type: sting

Example: `12345` | +| tax_id
_optional_ | VAT registration ID.

Type: string

Possible values: `67890` | + +**Example Request[](#example-request "Permalink to this headline")** + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.` + +**Example Response[](#example-response "Permalink to this headline")** + +```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 + } + } +``` +### Tracking Tags + + +#### GET accounts/:account\_id/tracking\_tags[](#get-accounts-account-id-tracking-tags "Permalink to this headline") + +Retrieve details for some or all tracking tags associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/tracking_tags` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| line\_item\_ids
_optional_ | Scope the response to just the tracking tags associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `96uzp` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.

Type: string

Example: `created_at-asc` | +| tracking\_tag\_ids
_optional_ | Scope the response to just the desired tracking tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `3m82` | +| 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82` + +**Example Response[](#example-response "Permalink to this headline")** + +```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 + } + ] + } +``` + +#### GET accounts/:account\_id/tracking\_tags/:tracking\_tag\_id[](#get-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline") + +Retrieve a specific tracking tag associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| tracking\_tag\_id
_required_ | A reference to the tracking tag you are operating with in the request.

Type: string

Example: `555j` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j` + +**Example Response[](#example-response "Permalink to this headline")** + +```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 + } + } +``` + +#### POST accounts/:account\_id/tracking\_tags[](#post-accounts-account-id-tracking-tags "Permalink to this headline") + +Associate a tracking tag with the specified line item. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/tracking_tags` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| line\_item\_id
_required_ | A reference to the line item you are operating with in the request.

Type: string

Example: `8v7jo` | +| tracking\_tag\_type
_required_ | The type of tracking tag.

Type: enum

Possible value: `IMPRESSION_TAG`, `CLICK_TRACKER` | +| tracking\_tag\_url
_required_ | The tracking tag url provided by the tracking partner.

Type: string

Example: `https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?line_item_id=fdwcl&tracking_tag_type=IMPRESSION_TAG&tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "line_item_id": "fdwcl", + "tracking_tag_type": "IMPRESSION_TAG", + "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309", + "account_id": "18ce54d4x5t" + } + }, + "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 + } + } +``` + +#### PUT accounts/:account\_id/tracking\_tags/:tracking\_tag\_id[](#put-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline") + +Associate a tracking tag with the specified line item. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| tracking\_tag\_url
_required_ | The tracking tag url provided by the tracking partner.

Type: string

Example: `https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` | + +**Example Request[](#example-request "Permalink to this headline")** + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/3m82?tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "tracking_tag_id": "3m82", + "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309", + "account_id": "18ce54d4x5t" + } + }, + "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": "2022-01-26T17:04:26Z", + "deleted": false + } + } +``` + +#### DELETE accounts/:account\_id/tracking\_tags/:tracking\_tag\_id[](#delete-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline") + +Disassociate a tracking tag from the specified line item. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| tracking\_tag\_id
_required_ | A reference to the tracking tag you are operating with in the request.

Type: string

Example: `555j` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "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": "2021-08-29T17:12:58Z", + "deleted": true + } + } +``` +### User Settings + + +(https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87) + +#### GET accounts/:account\_id/user\_settings/:user_id[](#get-accounts-account-id-user-settings-user-id "Permalink to this headline") + + +Retrieves user settings. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#get-accounts).
The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| user_id
_required_ | A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name.

Type: long

Example: `756201191646691328` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "user_id": "756201191646691328" + } + }, + "data": { + "notification_email": "user@domain.com", + "contact_phone": "", + "contact_phone_extension": "" + } + } +``` + +#### PUT accounts/:account\_id/user\_settings/:user_id[](#put-accounts-account-id-user-settings-user-id "Permalink to this headline") + +Updates user settings. Requires user context. Not accessible by account admins. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| account_id
_required_ | The identifier for the leveraged account. Appears within the resource's path and [GET accounts](/x-ads-api/campaign-management/reference#get-accounts).
The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| user_id
_required_ | A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name.

Type: long

Example: `756201191646691328` | +| notification_email
_optional_ | Email to use for account notifications.

Type: string

Example: `user@domain.com` | +| contact_phone
_optional_ | Contact phone number.

Type: string

Example: `202-555-0128` | +| contact\_phone\_extension
_optional_ | Extension for contact `contact_phone`.

Type: string

Example: `1234` | + +**Example Request[](#example-request "Permalink to this headline")** + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='user@domain.com'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"` + +**Example Response[](#example-response "Permalink to this headline")** + +```json + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "user_id": "756201191646691328" + "notification_email": "user@domain.com", + "subscribed_campaign_events": [ + "ACCOUNT_PERFORMANCE", + "PERFORMANCE_IMPROVEMENT" + ] + } + }, + "data": { + "notification_email": "user@domain.com", + "contact_phone": "", + "Contact_phone_extension": "" + } + } +``` \ No newline at end of file diff --git a/x-ads-api/catalog-management.mdx b/x-ads-api/catalog-management.mdx index ae6cdc41a..825ca1a57 100644 --- a/x-ads-api/catalog-management.mdx +++ b/x-ads-api/catalog-management.mdx @@ -1,7 +1,8 @@ --- title: Catalog Management keywords: ["catalog management", "product catalog", "catalog API", "manage catalog", "product catalog API", "catalog"] ---- + +description: The Catalog API is a commerce solution that gives advertisers the ability to set up product feeds, group products into sets, and holistically manage cat...--- ## Overview The Catalog API is a commerce solution that gives advertisers the ability to set up product feeds, group products into sets, and holistically manage catalog products. The Catalog API will be a core tool that enables programmatic catalog management and grants advertisers more control over how their catalogs are ingested and updated. diff --git a/x-ads-api/creatives.mdx b/x-ads-api/creatives.mdx index 21b41b5f0..0b8cdc178 100644 --- a/x-ads-api/creatives.mdx +++ b/x-ads-api/creatives.mdx @@ -1,5 +1,6 @@ --- title: Creatives +description: Manage promotable creatives on X including Tweets, images, GIFs, videos, and cards. Upload media and associate creatives with line items and campaigns. keywords: ["creatives", "ad creatives", "creative management", "ad creative API", "manage creatives", "advertising creatives"] --- @@ -80,7 +81,7 @@ Finally, create the Tweet using the POST accounts/:account\_id/tweet endpoint. C For detailed guidance on video uploading through the API, please see the [Video Upload Guide](/x-api/media/quickstart/media-upload-chunked). -Videos can also be promoted as pre-roll assets. See the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective) for a detailed explanation. +Videos can also be promoted as pre-roll assets. See the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective) for a detailed explanation. - (As of 2015-10-22) When uploading videos to be used in promoted content, the `media_category` parameter must be set with a value of `amplify_video` for all `INIT` command requests to the [POST media/upload (chunked)](/x-api/media/initialize-media-upload) endpoint. Using this new param ensures that the video is asynchronously pre-processed and prepared for use in promoted content. The `STATUS` command can be used to check completion of asynchronous processing after video upload. - The maximum promoted video length currently allowed is 10 mins with a file size of 500MB or less. @@ -118,10 +119,10 @@ The entire set of endpoints related to the above functionality is listed below: #### Scheduled Promoted Tweets -- [GET accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets) (retreive a list of all Scheduled Promoted Tweets) -- [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (lookup a Promoted Scheduled Tweet using its `id`) -- [POST accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management#post-accounts-account-id-scheduled-promoted-tweets) (create a new Scheduled Promoted Tweet) -- [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (delete an existing Scheduled Promoted Tweet using its `id`) +- [GET accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management/reference#get-accounts-account-id-scheduled-promoted-tweets) (retreive a list of all Scheduled Promoted Tweets) +- [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management/reference#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (lookup a Promoted Scheduled Tweet using its `id`) +- [POST accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management/reference#post-accounts-account-id-scheduled-promoted-tweets) (create a new Scheduled Promoted Tweet) +- [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management/reference#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (delete an existing Scheduled Promoted Tweet using its `id`) #### Scheduled Tweet View diff --git a/x-ads-api/fundamentals/accessing-ads-accounts.mdx b/x-ads-api/fundamentals/accessing-ads-accounts.mdx index 472a64ff4..bf530817f 100644 --- a/x-ads-api/fundamentals/accessing-ads-accounts.mdx +++ b/x-ads-api/fundamentals/accessing-ads-accounts.mdx @@ -1,14 +1,15 @@ --- title: Accessing Ads accounts keywords: ["ads accounts", "ad accounts", "access ads accounts", "account access", "ads account management", "account hierarchy"] ---- + +description: There are two different types of accounts involved in using the Ads API: advertising accounts and X user accounts. Throughout Ads API documentation, the...--- # User accounts vs Ad accounts There are two different types of accounts involved in using the Ads API: advertising accounts and X user accounts. Throughout Ads API documentation, the term “account” usually refers to the advertising account. * Advertising accounts are registered on **business.x.com** and identified in the API by account\_id. Advertising accounts link directly to funding sources and leverage content from one or more X user accounts as ‘promotable users’. Each advertising account can grant permission to one or more X user accounts. The advertising account, or “current account,” is represented in nearly every URL executed as an in-line :account\_id parameter. -* X user accounts (such as @AdsAPI) are identified by user_id in the Ads API. One or more of these accounts can be associated with an advertising account. The authenticated X user account making requests on the API is referred to as the ‘current user.’ A listing of advertising accounts that the current user has access to can be found with [GET accounts](/x-ads-api/campaign-management#accounts). ‘Promotable users’ are X handles that can be promoted by a specific advertising account. For more details about this, see [Obtaining Ads Account Access](/x-ads-api/introduction). +* X user accounts (such as @AdsAPI) are identified by user_id in the Ads API. One or more of these accounts can be associated with an advertising account. The authenticated X user account making requests on the API is referred to as the ‘current user.’ A listing of advertising accounts that the current user has access to can be found with [GET accounts](/x-ads-api/campaign-management/reference#accounts). ‘Promotable users’ are X handles that can be promoted by a specific advertising account. For more details about this, see [Obtaining Ads Account Access](/x-ads-api/introduction). ## Methods for Ad account access @@ -36,7 +37,7 @@ Each user will have a level of access as requested upon [application to the Ads ### Ad Account-level permissions -Each user that has access to an Ads Account will have a specific account-level permission: **Account administrator**, **Ad manager**, **Campaign analyst**, **Organic analyst**, and **Creative Manager**; see **business.x.com** for the latest documentation for account-level permissions. Applications should retrieve the permissions for the currently authenticated user via the [Authenticated User Access](/x-ads-api/campaign-management#authenticated-user-access) API endpoint to determine which API endpoints and Ads features they can access. +Each user that has access to an Ads Account will have a specific account-level permission: **Account administrator**, **Ad manager**, **Campaign analyst**, **Organic analyst**, and **Creative Manager**; see **business.x.com** for the latest documentation for account-level permissions. Applications should retrieve the permissions for the currently authenticated user via the [Authenticated User Access](/x-ads-api/campaign-management/reference#authenticated-user-access) API endpoint to determine which API endpoints and Ads features they can access. **Note:** Any user tokens used with the [Conversion API](/x-ads-api/measurement/web-conversions) must be for users with **Account administrator** or **Ad manager** account-level permissions.                                                                                                                                               @@ -54,7 +55,7 @@ This option requires the advertiser to [grant your @username](https://business. This allows you to call the API using the OAuth tokens of your own @username rather than the advertiser’s OAuth tokens. The key distinction on this option is that you may only create Promoted-Only Posts if the Post delegation/composer permission has been granted to your @username. -To gain access to create Promoted-Only Posts on behalf of the `FULL` promotable user on the account, you must also be granted access to create Posts in this flow. That will enable access via the `TWEET_COMPOSER` permission on the [GET accounts/:account\_id/authenticated\_user_access](/x-ads-api/campaign-management#accounts) endpoint. +To gain access to create Promoted-Only Posts on behalf of the `FULL` promotable user on the account, you must also be granted access to create Posts in this flow. That will enable access via the `TWEET_COMPOSER` permission on the [GET accounts/:account\_id/authenticated\_user_access](/x-ads-api/campaign-management/reference#accounts) endpoint. ## Differences between these methods diff --git a/x-ads-api/fundamentals/currency.mdx b/x-ads-api/fundamentals/currency.mdx index 0f8673393..397ec33b9 100644 --- a/x-ads-api/fundamentals/currency.mdx +++ b/x-ads-api/fundamentals/currency.mdx @@ -1,7 +1,8 @@ --- title: Currency keywords: ["currency", "ISO-4217", "currency codes", "micros", "currency format", "money format", "currency values"] ---- + +description: The type of a currency is identified using [ISO-4217](http://en.--- The type of a currency is identified using [ISO-4217](http://en.wikipedia.org/wiki/ISO_4217). This is a three-letter string like `USD` or `EUR`. The value of a currency is represented in micros. For USD, $5.50 is encoded as 5.50*1e6, or 5,500,000. To represent a “whole value”, you need to multiply the local micro by 1e6 (1\_000\_000) for all currencies. diff --git a/x-ads-api/fundamentals/error-codes-and-responses.mdx b/x-ads-api/fundamentals/error-codes-and-responses.mdx index bb1770c24..62d66c3bc 100644 --- a/x-ads-api/fundamentals/error-codes-and-responses.mdx +++ b/x-ads-api/fundamentals/error-codes-and-responses.mdx @@ -1,14 +1,15 @@ --- title: Error codes and responses keywords: ["Ads API errors", "error codes", "Ads API error handling", "error responses", "API errors", "error codes"] ---- + +description: Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object(s) requested, created, modified, or delete...--- ## Typical Response Structure Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object(s) requested, created, modified, or deleted along with an expression of the server’s interpretation of your request. If you had issued a successful request you would receive as part of your response a `request` node echoing back your request. -_Example:_ [GET accounts/abcdefg/campaigns?with_deleted=true](/x-ads-api/campaign-management#campaigns) +_Example:_ [GET accounts/abcdefg/campaigns?with_deleted=true](/x-ads-api/campaign-management/reference#campaigns) ```json { diff --git a/x-ads-api/fundamentals/hierarchy-and-terminology.mdx b/x-ads-api/fundamentals/hierarchy-and-terminology.mdx index 22663e980..a045c17e4 100644 --- a/x-ads-api/fundamentals/hierarchy-and-terminology.mdx +++ b/x-ads-api/fundamentals/hierarchy-and-terminology.mdx @@ -1,7 +1,8 @@ --- title: "Ads API hierarchy and terminology" keywords: ["Ads API hierarchy", "advertising hierarchy", "ads terminology", "account structure", "campaign structure", "ads structure"] ---- + +description: To be successful on the Ads API, it’s important to understand how entities in X Ads relate to each other. This tutorial goes over the basics of the X Ad...--- To be successful on the Ads API, it’s important to understand how entities in X Ads relate to each other. This tutorial goes over the basics of the X Ads object hierarchy. @@ -13,7 +14,7 @@ Ad groups, known as [line items](https://developer.x.com/content/developer-twitt ## Account Media -A collection of creatives that have been uploaded to an ads account as [account media](/x-ads-api/creatives#account-media) that can include promoted video [pre-roll assets](/x-ads-api/campaign-management#video-views-preroll-objective), also referred to as in-stream ads, and images that can be promoted on the [X Audience Platform](https://developer.x.com/content/developer-twitter/en/docs/ads/measurement/overview/twitter-audience-platform). +A collection of creatives that have been uploaded to an ads account as [account media](/x-ads-api/creatives#account-media) that can include promoted video [pre-roll assets](/x-ads-api/campaign-management/reference#video-views-preroll-objective), also referred to as in-stream ads, and images that can be promoted on the [X Audience Platform](https://developer.x.com/content/developer-twitter/en/docs/ads/measurement/overview/twitter-audience-platform). ## Ads Accounts diff --git a/x-ads-api/fundamentals/making-authenticated-requests.mdx b/x-ads-api/fundamentals/making-authenticated-requests.mdx index 103fd2e4b..88d81bd5c 100644 --- a/x-ads-api/fundamentals/making-authenticated-requests.mdx +++ b/x-ads-api/fundamentals/making-authenticated-requests.mdx @@ -1,7 +1,8 @@ --- title: Making Authenticated Requests keywords: ["Ads API authentication", "authenticated requests", "Ads API auth", "OAuth Ads API", "Ads API requests", "authentication"] ---- + +description: Accessing the X Ads API endpoints requires your application to send authenticated web requests securely using TLS to https://ads-api.--- Accessing the X Ads API endpoints requires your application to send authenticated web requests securely using TLS to https://ads-api.x.com. The following sections will provide an overview of making authenticated API requests, setting up [Twurl](https://github.com/twitter/twurl#getting-started) to interact with the API, and extending your application to support OAuth 1.0a and make requests against your Ads account. @@ -44,7 +45,7 @@ See [Error Codes & Responses](/x-ads-api/fundamentals/error-codes-and-responses) Most resource URLs feature one or more in-line parameter. Many URLs also take explicitly declared parameters on the query string or, for POST or PUT requests, in the body. -In-line parameters are denoted with a pre-pended colon (”:”) in the **Resource Path** section of each resource. For example, if the account you were working on were identified as `"abc1"` and you were [retrieving the campaigns associated with an account](/x-ads-api/campaign-management#campaigns), you would access that list by using the URL `https://ads-api.x.com/6/accounts/abc1/campaigns`. By specifying the in-line `account_id` parameter described in the resource URL (`https://ads-api.x.com/6/accounts/:account_id/campaigns`), you’ve scoped the request to objects associated only with that account. +In-line parameters are denoted with a pre-pended colon (”:”) in the **Resource Path** section of each resource. For example, if the account you were working on were identified as `"abc1"` and you were [retrieving the campaigns associated with an account](/x-ads-api/campaign-management/reference#campaigns), you would access that list by using the URL `https://ads-api.x.com/6/accounts/abc1/campaigns`. By specifying the in-line `account_id` parameter described in the resource URL (`https://ads-api.x.com/6/accounts/:account_id/campaigns`), you’ve scoped the request to objects associated only with that account. ## Using Access Tokens @@ -92,7 +93,7 @@ After [installing and authorizing Twurl](https://github.com/twitter/twurl#gettin ```bash twurl -H "ads-api.x.com" "/5/accounts/" ``` -Take some time to get familiar with Twurl and the API by following this [step-by-step](/x-ads-api/campaign-management#creating-a-campaign-step-by-step) tutorial for creating a campaign through the API. +Take some time to get familiar with Twurl and the API by following this [step-by-step](/x-ads-api/campaign-management/reference#creating-a-campaign-step-by-step) tutorial for creating a campaign through the API. ## Testing with Postman diff --git a/x-ads-api/fundamentals/pagination.mdx b/x-ads-api/fundamentals/pagination.mdx index 85971fbde..58d3ea4d5 100644 --- a/x-ads-api/fundamentals/pagination.mdx +++ b/x-ads-api/fundamentals/pagination.mdx @@ -1,7 +1,8 @@ --- title: Pagination keywords: ["Ads API pagination", "pagination", "cursor pagination", "page through results", "Ads API pagination tokens"] ---- + +description: In order to support a larger maximum number of campaigns and efficient retrieval of all entities associated with an account, the Advertiser API now supp...--- In order to support a larger maximum number of campaigns and efficient retrieval of all entities associated with an account, the Advertiser API now supports pagination on many GET endpoints. The paging mechanism is easy to use and very similar to the REST API’s cursor-based pagination as described in [Using cursors to navigate collections](https://developer.x.com/en/docs/x-api/v1/pagination). diff --git a/x-ads-api/fundamentals/rate-limiting.mdx b/x-ads-api/fundamentals/rate-limiting.mdx index b3914c048..3ddaec5aa 100644 --- a/x-ads-api/fundamentals/rate-limiting.mdx +++ b/x-ads-api/fundamentals/rate-limiting.mdx @@ -1,7 +1,8 @@ --- title: Rate limiting keywords: ["Ads API rate limits", "rate limiting", "Ads API throttling", "rate limits", "request limits", "Ads API limits"] ---- + +description: The Advertiser API is rate limited similarly to REST API v1. 1, as documented here: [REST API Rate Limiting in v1.--- The Advertiser API is rate limited similarly to REST API v1.1, as documented here: [REST API Rate Limiting in v1.1](https://developer.x.com/content/developer-twitter/en/docs/basics/rate-limits). Unlike REST API v1.1, there is no programmatic index of the limits per endpoint. The endpoint rate limits and reset windows are communicated via HTTP response headers.  All rate limiting in the Ads API utilizes OAuth 1.0A. @@ -25,7 +26,7 @@ For ad account level rate limited endpoints, the user level rate limit is set at 2) Request multiple entities in a single request: Some endpoints allow you to specify a comma-separated list of values, to retrieve multiple pieces of similar data. This can reduce the overall number of calls you make and thus leverage rate limit more efficiently. -3) Request maximum “count” in your requests: Some endpoints such as [GET accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#targeting-criteria) are strongly recommended to call with maximum count value to return 1000 objects instead of the default of 200. +3) Request maximum “count” in your requests: Some endpoints such as [GET accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#targeting-criteria) are strongly recommended to call with maximum count value to return 1000 objects instead of the default of 200. ## Analytics Syncing diff --git a/x-ads-api/fundamentals/sandbox.mdx b/x-ads-api/fundamentals/sandbox.mdx index eac9c5b11..2b345b3a1 100644 --- a/x-ads-api/fundamentals/sandbox.mdx +++ b/x-ads-api/fundamentals/sandbox.mdx @@ -1,20 +1,21 @@ --- title: Sandbox keywords: ["sandbox", "test environment", "Ads API sandbox", "testing", "sandbox environment", "test API"] ---- + +description: The sandbox is an environment for you to test and build your Ads API implementation. Campaigns created via the sandbox will not be served to users and t...--- The sandbox is an environment for you to test and build your Ads API implementation. Campaigns created via the sandbox will not be served to users and test records for objects such as Funding Instruments can be created dynamically. Using the sandbox is as simple as calling the appropriate hostname of ads-api-sandbox.x.com but it also contains some unique functionality found only in the sandbox. -Make an initial request to [POST accounts](/x-ads-api/campaign-management#post-accounts) to create a new advertiser account. The response from this call will contain an account_id that can be used for subsequent requests. These endpoints enable consumers to create and test against multiple advertiser accounts. +Make an initial request to [POST accounts](/x-ads-api/campaign-management/reference#post-accounts) to create a new advertiser account. The response from this call will contain an account_id that can be used for subsequent requests. These endpoints enable consumers to create and test against multiple advertiser accounts. ### Sandbox-Only Endpoint List: -* [POST accounts](/x-ads-api/campaign-management#post-accounts) Create an account on the sandbox -* [POST accounts/:account_id/features](/x-ads-api/campaign-management#post-accounts-account-id-features) Add an account feature to an account on the sandbox -* [POST accounts/:account\_id/funding\_instruments](/x-ads-api/campaign-management#post-accounts-account-id-funding-instruments) Add a funding instrument to an account on the sandbox -* [DELETE accounts/:account_id](/x-ads-api/campaign-management#delete-accounts-account-id) Delete an account on the sandbox -* [DELETE accounts/:account_id/features](/x-ads-api/campaign-management#delete-accounts-account-id-features) Delete an account feature from an account on the sandbox -* [DELETE accounts/:account\_id/funding\_instruments/:funding\_instrument\_id](/x-ads-api/campaign-management#delete-accounts-account-id-funding-instruments-funding-instrument-id) Delete a funding instrument from an account on the sandbox +* [POST accounts](/x-ads-api/campaign-management/reference#post-accounts) Create an account on the sandbox +* [POST accounts/:account_id/features](/x-ads-api/campaign-management/reference#post-accounts-account-id-features) Add an account feature to an account on the sandbox +* [POST accounts/:account\_id/funding\_instruments](/x-ads-api/campaign-management/reference#post-accounts-account-id-funding-instruments) Add a funding instrument to an account on the sandbox +* [DELETE accounts/:account_id](/x-ads-api/campaign-management/reference#delete-accounts-account-id) Delete an account on the sandbox +* [DELETE accounts/:account_id/features](/x-ads-api/campaign-management/reference#delete-accounts-account-id-features) Delete an account feature from an account on the sandbox +* [DELETE accounts/:account\_id/funding\_instruments/:funding\_instrument\_id](/x-ads-api/campaign-management/reference#delete-accounts-account-id-funding-instruments-funding-instrument-id) Delete a funding instrument from an account on the sandbox diff --git a/x-ads-api/fundamentals/sorting.mdx b/x-ads-api/fundamentals/sorting.mdx index 904c2d694..70874e22d 100644 --- a/x-ads-api/fundamentals/sorting.mdx +++ b/x-ads-api/fundamentals/sorting.mdx @@ -1,18 +1,19 @@ --- title: Sorting keywords: ["sorting", "sort results", "Ads API sorting", "sort parameters", "order results", "sort data"] ---- + +description: Sorting is available for most Ads API collection endpoints (that return a list of objects). Depending on the endpoint, you will find various parameters ...--- Sorting is available for most Ads API collection endpoints (that return a list of objects). Depending on the endpoint, you will find various parameters enabled for sorting. Most fields returned by these parameters (except for IDs and ENUMs) will be sortable. | API Collection | Sortable Parameters | | :--- | :--- | -| [Accounts](/x-ads-api/campaign-management#accounts) | `created_at`, `updated_at`, `deleted`, `name` | -| [Funding Instruments](/x-ads-api/campaign-management#funding-instruments) | `created_at`, `updated_at`, `deleted`, `funded_amount_local_micro`, `start_time`, `end_time` | -| [Campaigns](/x-ads-api/campaign-management#campaigns) | `created_at`, `updated_at`, `deleted`, `name`, `start_time`, `end_time`, `daily_budget_amount_local_micro`, `total_budget_amount_local_micro`, `standard_delivery` | -| [Line Items](/x-ads-api/campaign-management#line-items) | `created_at`, `updated_at`, `deleted`, `bid_amount_local_micro` | +| [Accounts](/x-ads-api/campaign-management/reference#accounts) | `created_at`, `updated_at`, `deleted`, `name` | +| [Funding Instruments](/x-ads-api/campaign-management/reference#funding-instruments) | `created_at`, `updated_at`, `deleted`, `funded_amount_local_micro`, `start_time`, `end_time` | +| [Campaigns](/x-ads-api/campaign-management/reference#campaigns) | `created_at`, `updated_at`, `deleted`, `name`, `start_time`, `end_time`, `daily_budget_amount_local_micro`, `total_budget_amount_local_micro`, `standard_delivery` | +| [Line Items](/x-ads-api/campaign-management/reference#line-items) | `created_at`, `updated_at`, `deleted`, `bid_amount_local_micro` | | [Cards](https://developer.x.com/en/docs/ads/creatives/api-reference/image-app-download) | `created_at`, `updated_at`, `deleted`, `name` | -| [Promoted Accounts](/x-ads-api/campaign-management#advertiser-api) | `created_at`, `updated_at`, `deleted`, `paused` | -| [Promoted Tweets](/x-ads-api/campaign-management#promoted-tweets) | `created_at`, `updated_at`, `deleted`, `paused` | +| [Promoted Accounts](/x-ads-api/campaign-management/reference#advertiser-api) | `created_at`, `updated_at`, `deleted`, `paused` | +| [Promoted Tweets](/x-ads-api/campaign-management/reference#promoted-tweets) | `created_at`, `updated_at`, `deleted`, `paused` | | [App Event Tags](/x-ads-api/measurement/mobile-conversions#app-event-tags) | `created_at`, `updated_at`, `deleted`, `post_view_attribution_window`, `post_engagement_attribution_window`, `assisted_conversion`, `provider_app_event_name` | ## Getting Started @@ -372,23 +373,4 @@ Below is a sample API request to return all line items by the `bid_amount_local_ "charge_by": "ENGAGEMENT", "product\_type": "PROMOTED\_TWEETS", "bid_unit": "ENGAGEMENT", - "total\_budget\_amount\_local\_micro": 6000000, - "objective": "ENGAGEMENTS", - "id": "1kl0l", - "paused": false, - "optimization": "DEFAULT", - "categories": \[ - - \], - "currency": "USD", - "created_at": "2014-09-24T01:45:09Z", - "updated_at": "2014-09-24T01:51:54Z", - "include\_sentiment": "POSITIVE\_ONLY", - "campaign_id": "1mj5d", - "creative_source": "MANUAL", - "deleted": false - } - \], - "next_cursor": null -} -``` + "total\ \ No newline at end of file diff --git a/x-ads-api/fundamentals/timezones.mdx b/x-ads-api/fundamentals/timezones.mdx index b913a8a01..709035306 100644 --- a/x-ads-api/fundamentals/timezones.mdx +++ b/x-ads-api/fundamentals/timezones.mdx @@ -1,13 +1,14 @@ --- title: Timezones keywords: ["timezones", "time zones", "timezone handling", "timezone format", "timezone conversion", "timezone settings"] ---- + +description: Datetime values are always returned in UTC time (as indicated by the Z at the end of the datetime value. ) Datetimes may be specified in any timezone in...--- ## Timezones, Accounts, and Billing Datetime values are always returned in UTC time (as indicated by the Z at the end of the datetime value.) Datetimes may be specified in any timezone in a POST or PUT command using the ISO 8601 standard format for timezone. Time is represented using a subset of [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601). More specifically, the strptime string for our date format is `%Y-%m-%dT%l:%M:%S%z`. The timezone of the advertiser’s account determines the actual time that the official billing numbers are frozen. -When querying the API at the account level ([GET accounts](/x-ads-api/campaign-management#accounts)), you will get timezone information that looks like this: +When querying the API at the account level ([GET accounts](/x-ads-api/campaign-management/reference#accounts)), you will get timezone information that looks like this: ```json { diff --git a/x-ads-api/fundamentals/versioning.mdx b/x-ads-api/fundamentals/versioning.mdx index 4ce837b42..8a49fd0d5 100644 --- a/x-ads-api/fundamentals/versioning.mdx +++ b/x-ads-api/fundamentals/versioning.mdx @@ -1,7 +1,8 @@ --- title: Versions keywords: ["Ads API versions", "API versioning", "version history", "API versions", "version updates", "Ads API version"] ---- + +description: For the most up to date information on historical versions of the X Ads API, please reference the information below. | Version | Path | Introduction Dat...--- For the most up to date information on historical versions of the X Ads API, please reference the information below. @@ -145,13 +146,13 @@ Two things to note: **Flexibility around retrieving** -The [GET accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) endpoint now supports multiple line item IDs. The line\_item\_ids parameter, which accepts up to 200 IDs, is required. Previously, only a single line item was accepted, which made syncing difficult. With this change, it’s now possible to retrieve more targeting in less time. +The [GET accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#get-accounts-account-id-targeting-criteria) endpoint now supports multiple line item IDs. The line\_item\_ids parameter, which accepts up to 200 IDs, is required. Previously, only a single line item was accepted, which made syncing difficult. With this change, it’s now possible to retrieve more targeting in less time. The following endpoints now also support multiple line item IDs, though the line\_item\_ids parameter is optional for these. * [GET accounts/:account\_id/line\_item_apps](https://developer.x.com/en/docs/x-ads-api/campaign-management/api-reference/line-item-apps#get-accounts-account-id-line-item-apps) -* [GET accounts/:account\_id/media\_creatives](/x-ads-api/campaign-management#get-accounts-account-id-media-creatives) -* [GET accounts/:account\_id/promoted\_accounts](/x-ads-api/campaign-management#get-accounts-account-id-promoted-accounts) +* [GET accounts/:account\_id/media\_creatives](/x-ads-api/campaign-management/reference#get-accounts-account-id-media-creatives) +* [GET accounts/:account\_id/promoted\_accounts](/x-ads-api/campaign-management/reference#get-accounts-account-id-promoted-accounts) * [GET accounts/:account\_id/preroll\_call\_to\_actions](/x-ads-api/creatives#preroll-call-to-actions) #### Changed @@ -166,317 +167,4 @@ The way that draft campaigns and line items are retrieved has been updated. Now, **Network activation duration targeting** -The Ads API has resolved a display issue where, after adding Network Activation Duration targeting, the targeting type in the response included an \_IN\_SEC suffix. Having a reference to seconds was confusing as Network Activation Duration is always represented in months. This fix makes the representation consistent and reduces confusion. - -| **v4** | **v5** | -| :--- | :--- | :--- | -| `NETWORK_ACTIVATION_DURATION_IN_SEC` | `NETWORK_ACTIVATION_DURATION` | | - -**Total counts and cursors** - -In v5, with\_total\_count and cursor are exclusive. Specifying both in a request will return the EXCLUSIVE\_PARAMETERS error code. Prior to v5, with\_total_count was ignored when cursorwas specified. This change makes the relationship explicit.. - -#### Removed - -Three fields are being removed from Ads API responses: preview\_url, account\_id, and parent_ids. The engineering level of effort for these three is minimal. - -* In v4, it was announced that the preview\_url response parameter for cards was always null. The final step in this migration is to remove preview\_url from all cards responses. -* The account_id response attribute is being removed for the following resources given that the ads account ID is already present in the URL as well as in request.params. (It is intentional to exclude funding instruments from this list as parent IDs should be present in response objects, where possible, and account IDs are parent entities to funding instruments.) - * Account media - * App event providers - * App event tags - * Campaigns - * Cards - * Line items - * Promotable users - * Targeting criteria -* For [GET accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) requests, we no longer return the parent_ids field as it was always an empty array. - -**Non-media app cards** - -In v5, non-media app cards are no longer supported. [Previously](https://devcommunity.x.com/t/deprecation-announcement-app-download-cards/87807), the ability to create or edit non-media app cards was removed. Now, the remaining endpoints for this resource are being deprecated. - -* Note: This does **not** affect image and video app download cards. - -**Account media creates** - -The POST accounts/:account\_id/account\_media endpoint is no longer available in v5. Other endpoints for this resource are _not_ affected. The reason for this change is that, when adding media to the [Media Library](/x-ads-api/creatives#media-library), there are cases when those assets _automatically_ get added as Account Media entities and trying to add an already-existing asset to the Account Media resource results in an error. This happens in the following cases. - -* `AMPLIFY_VIDEO` assets added to the Media Library are automatically added as Account Media asset with the `PREROLL` creative type. -* Images with specific dimensions added to the Media Library are automatically added as Account Media assets. The creative type (e.g., `INTERSTITIAL`) depends on the image dimensions. (For dimensions, see our [Enumerations](/x-ads-api/introduction) page.) - - -### v4 - -Version 4 of the Ads API is launching today, August 28, 2018. - -This release includes improvements to our [Audiences](/x-ads-api/audiences) product, including a new API interface powered by a more robust audience processing backend. Version 4 also includes a set of endpoints for managing user, account, and tax settings. In addition, the accounts/:account_id/videos endpoints are being deprecated. This release also includes a few minor parameter and and response name changes. - -As with version 3, we are providing a 6 month transition period. On **2019-02-28**, version 3 of the Ads API will no longer be available. We encourage all partners to migrate to the latest version of the API as soon as possible to avoid any service disruptions. See our [Versions](/x-ads-api/introduction) page for details on our versioning strategy. - -#### New - -***Audience API*** - -The new Audiences API is built on our new audience processing backend that provides enhanced robustness and reliability. This new endpoint will allow partners to provide multiple user identifier types for a single user, which means that we are able to use additional signals for matching. Reference documentation for the new Audience endpoint can be found [here](/x-ads-api/audiences). We plan to continue to release updates and improvements to this product throughout the rest of year. - -The following endpoints will no longer be available in v4 due to redundant functionality (they will still work in v3 and will be fully **sunset** when v3 is no longer available): - -* TON Upload: - * GET accounts/:account\_id/tailored\_audience_changes - * GET accounts/:account\_id/tailored\_audience\_changes/:tailored\_audience\_change\_id - * POST accounts/:account\_id/tailored\_audience_changes - * PUT accounts/:accounti\_d/tailored\_audiences/global\_opt\_out -* Real Time Audiences: - * POST tailored\_audience\_memberships - -Finally, the `list_type` parameter will be removed from the request and response on _all_ [Tailored Audiences endpoints](/x-ads-api/audiences) in version 4. - -***Settings Endpoints*** - -We now provide the ability for account administrators to set and update user, account, and tax settings. [User settings](/x-ads-api/campaign-management#get-accounts-account-id-user-settings-user-id) correspond to the user-specific contact preferences for a given ads account. Using the [PUT accounts/:account_id](/x-ads-api/campaign-management#put-accounts-account-id) endpoint, advertisers can now update their account name and industry type. Finally, the [tax settings](/x-ads-api/campaign-management#get-accounts-account-id-tax-settings) endpoints allow advertisers in countries where a value added tax (VAT) is charged to update information such as the company name, address, VAT ID, and whether the account is owned by the advertiser or by an agency advertising on behalf of an advertiser. - -#### Changed - -***Universal Lookalike Renames*** - -We’re updating the enum values for the `lookalike_expansion` parameter on the [POST accounts/:account\_id/line\_items](/x-ads-api/campaign-management#post-accounts-account-id-line-items) and [PUT accounts/:accountit/line\_items/:line\_item_id](/x-ads-api/campaign-management#put-accounts-account-id-line-items-line-item-id) endpoints. - -| **v3** | **v4** | -| :--- | :--- | -| `NARROW` | `DEFINED` | -| `BALANCED` | `EXPANDED` | - -**Using `country_code` everywhere** - -As part of a larger effort around [consistency](https://devcommunity.x.com/t/feedback-ads-api-consistency/109145) on the Ads API, we’re renaming the parameters on the following endpoints from `app_country_code` to `country_code`. - -* [POST accounts/:account\_id/cards/image\_app_download](https://devcommunity.x.com/t/ads-api-version-11/168814) -* [PUT accounts/:account\_id/cards/image\_app\_download/:card\_id](https://developer.x.com/content/developer-twitterhttps://developer.x.com/en/docs/ads/creatives/api-reference/image-app-download#put-accounts-account-id-cards-image-app-download-card-id) -* [POST accounts/:account\_id/cards/video\_app_download](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/video-app-download#post-accounts-account-id-cards-video-app-download) -* [PUT accounts/:account\_id/cards/video\_app\_download/:card\_id](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/video-app-download#put-accounts-account-id-cards-video-app-download-card-id) - -This does not impact the behavior or accepted values for these parameters and is purely a naming change. - -**`preview_url` always null** - -As promised in the v3 announcement, all existing cards now have a `card_uri`. As a result, the `preview_url` value will always be `null`. - -As a reminder, associate a card with a Tweet using its `card_uri` value. See the following example request. - - $ twurl -X POST -H ads-api.x.com "/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496" - -#### Removed - -**Video endpoints** - -The accounts/:account_id/videos endpoints will no longer be available in v4. This endpoint has been made obsolete by the introduction of the [Media Library](/x-ads-api/creatives#get-accounts-account-id-media-library) endpoints. See the following usage comparison. - -- v3 videos endpoint: `twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos"` - -- v4 media library endpoint for videos: `twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"` - -The Media Library endpoints are in full parity with the videos endpoints and also support additional functionality such as the ability to handle images and GIFs. Partners are requested to use the Media Library exclusively for any media management. - -**`as_user_id` in Tweet View** - -The `as_user_id` parameter available on the [GET accounts/:account\_id/tweet/preview/:tweet\_id](/x-ads-api/creatives#get-accounts-account-id-tweets) endpoint will no longer be accepted. The preview will always be rendered as the Tweet’s author. - -### v3 - -Version 3 of the Ads API [launched](https://devcommunity.x.com/t/ads-api-version-3/100732) on February 1, 2018. Version 2 of the Ads API will reach its end of life on August 1, 2018. - -This release includes our new Audience Intelligence product, access to the Media Library, and improved card workflows. We are also announcing the deprecation of the [PUT accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) endpoint. Finally, version 3 includes a few minor parameter and response changes and a lower batch size limit. - -As with [version 2](https://devcommunity.x.com/t/ads-api-version-2/90360), we are giving partners **6 months **to transition. On **2018-08-01**, v2 of the Ads API will be shut off. We encourage all partners and developers to migrate to v3 as soon as possible. - -**Audience Intelligence** - -Audience Intelligence delivers real-time insights into the top hashtags,@handles, and events most relevant to a given X audience. For example, enter Male 18-34 in the US and you’ll see#nintendoswitch,#cardinal, and@ricegumtrending amongst this audience. - -The Audience Intelligence [endpoints](/x-ads-api/audiences) will provide the following functionality: - -* Given an input audience, retrieve the top relevant hashtags,@handlesand events. -* Given an input audience, retrieve key demographic information (such as age, gender, and household income). -* Given a keyword, retrieve the Tweet volume time series - -**Media Library** - -The [Media Library](/x-ads-api/creatives#get-accounts-account-id-media-library) provides the ability to manage images, GIFs, and videos for ads accounts. These media objects can be used in Tweets and to create cards. They can also be reused in multiple creatives, eliminating the need to upload the same asset multiple times. - -Objects in the library are identified by amedia_key. Media keys are string values in the following format:13_875943225764098048, for example. In the Ads API, we are moving toward using media keys for all media. - -**Improved card workflow** - -All of our cards endpoints now support media keys. This enables objects in the Media Library to be used to create or update cards. - -In addition, we’re introducing two new endpoints for [retrieving card details](/x-ads-api/creatives#fetching-cards). These endpoints can be used to look up cards used in Tweets or Scheduled Tweets, for example, by specifying either thecard_uriorid. Previously, this was not possible. - -#### Other changes - -In addition to these new features, we’re including the following changes to version 3. - -**New** - -* The [GET insights/keywords/search](/x-ads-api/audiences) endpoint response now includes a related_keywords attribute with 30 terms related to the input keywords. - -**Changed** - -* The maximum targeting criteria batch size is now 500. -* Thecard_uriandpreview_urlresponse attributes are now mutually exclusive. When a card has acard_urithepreview_urlwill benull. When a card does not have acard_uri, only thepreview_urlwill be returned. - * All cards created as of 2018-01-29 will have acard_uri. - * By version 4, all existing cards will have acard_uri. -* It is no longer possible to _create_ cards with 5:2 images. While _existing_ 5:2 image-based cards will still work, we encourage partners to switch to using the higher-performing 1.91:1 or 1:1 aspect ratios (where supported) - -**Removed** - -* The [PUT accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) endpoint is no longer available. We’ve decided to make this change because the replace behavior with this endpoint caused advertiser confusion and it was not consistent with our other PUT endpoints that update a single resource at a time. Instead, partners should use the [POST batch/accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#post-batch-accounts-account-id-targeting-criteria) endpoint, which provides greater flexibility including the ability to both add and remove targeting in a single request. -* The paused response attribute is no longer returned for funding instruments. Instead, look to the entity_status response attribute to determine whether or not a funding instrument is paused. In addition, because paused and cancelled correspond to the same value, cancelled is no longer returned in the response, either. -* We have removed the card_id parameter from the [GET accounts/:account_id/tweet/preview](/x-ads-api/creatives#get-accounts-account-id-tweets) endpoint. -* Because it is not possible to retrieve deleted Scheduled Tweets, the with_deleted parameter is no longer supported. -* The draft_only parameter has been removed from the following endpoints as these entities can never be in a draft state: - * [GET accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) - * [GET accounts/:account\_id/promoted\_tweets](/x-ads-api/campaign-management#get-accounts-account-id-promoted-tweets) - * [GET accounts/:account\_id/promoted\_accounts](/x-ads-api/campaign-management#get-accounts-account-id-promoted-accounts) - * [GET accounts/:account\_id/media\_creatives](/x-ads-api/campaign-management#get-accounts-account-id-media-creatives) - * [GET accounts/:account\_id/preroll\_call\_to\_actions](/x-ads-api/creatives#get-accounts-account-id-preroll-call-to-actions) - -**Note** - -Both Video Website Cards and Scheduled Tweets are now out of beta. See [this thread](https://devcommunity.x.com/t/announcement-update-to-scheduled-tweets/94869) for the changes we’ve made to Scheduled Tweets since launch. This includes the ability to generate HTML [previews](https://devcommunity.x.com/t/announcement-tweet-preview-improvements/96577) for Scheduled Tweets. - -### v2 - -Version 2 of the Ads API [launched](https://devcommunity.x.com/t/ads-api-version-2/90360) on July 10, 2017. Version 1 of the Ads API will reach its end of life on January 10, 2018. - -**Breaking Changes/Deprecations[¶](#breaking-changes-deprecations "Permalink to this headline")** - -* `total_count` is now an optional response attribute. It will only be available if `with_total_count` is set to `true` -* `paused` and `draft_only` fields on `line_items` and `campaigns` request and response objects are replaced by a single `entity_status` parameter -* The `status` parameter has been renamed to `text` on the [POST accounts/:account_id/tweet](/x-ads-api/creatives) and [GET accounts/:account_id/tweet/preview](/x-ads-api/creatives#get-accounts-account-id-tweets) endpoints -* The [GET targeting_criteria/locations](/x-ads-api/campaign-management#get-targeting-criteria-locations) endpoint’s `location_type` enums are now plural. `COUNTRY` is now `COUNTRIES`, `REGION` is now `REGIONS`, and so on. The one exception is that, in v2, `CITY` is now `METROS`, to correctly reflect the fact that the location type refers to Designated Marker Areas (DMAs) or “metros”. -* `display_properties` on the PUT accounts/:account\_id/promoted\_tweets endpoints. This value will also no longer be returned as part of the response -* As a result of the previous point, it is no longer possible to update (PUT) promoted_tweets entities -* The `line_item_id` parameter on the [GET accounts/:account\_id/promoted\_tweets](/x-ads-api/campaign-management#get-accounts-account-id-promoted-tweets) endpoint has been removed - -* It will no longer be possible to create 5:2 Website Cards  on the v2 endpoints -* `data_type` response attribute is no longer returned - -**New Features[¶](#new-features "Permalink to this headline")** - -1. Cards v2 -2. Draft campaigns/line item creations and activations -3. Scheduled Tweets -4. Async Job Summaries - -**Cards v2[¶](#cards-v2 "Permalink to this headline")** - -* The `card_uri` request parameter should be used in favor of appending the `preview_url` to the Tweet text when associating a card with a Tweet -* If the `card_uri` param is not returned in the response (during the card creation step) then use the `preview_url` -* All new card formats will be natively availabe on the API, taking advantage of the `card_uri` parameter. - -**New Card Formats:[¶](#new-card-formats "Permalink to this headline")** - -* Video Website Cards: - - * [GET accounts/:account\_id/cards/video\_website](https://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#get-accounts-account-id-cards-video-website) - * [GET accounts/:account\_id/cards/video\_website/:card_id](https://developer.x.comhttps://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#get-accounts-account-id-cards-video-website-card-id) - * [POST accounts/:account\_id/cards/video\_website](https://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#post-accounts-account-id-cards-video-website) - * [PUT accounts/:account\_id/cards/video\_website/:card_id](https://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#put-accounts-account-id-cards-video-website-card-id) - * [DELETE accounts/:account\_id/cards/video\_webiste/:card_id](https://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#delete-accounts-account-id-cards-video-website-card-id) - - -**Draft Campaigns[¶](#draft-campaigns "Permalink to this headline")** - -Draft Camapiangs have been available to view via the [GET accounts/:account_id/camapaigns](/x-ads-api/campaign-management#get-accounts-account-id-campaigns) endpoint. With v2, it is now possible to create/activate draft campaigns via the API. - -* The `entity_status` parameter value on the [POST accounts/:account\_id/line\_items](/x-ads-api/campaign-management#post-accounts-account-id-line-items) and [POST accounts/:account_id/campaigns](/x-ads-api/campaign-management#post-accounts-account-id-campaigns) endpoints can be set to `DRAFT` in order create any new draft campaigns or line items. -* The set of required parameters for a newly created draft: - -| Draft Campaign | Draft Line Item | -| :--- | :--- | -| `funding_instrument_id` | `campaign_id` | -| `name` | `objective` | -| `start_time` | `product_type` | -| | `placements` | - -**Notes[¶](#notes "Permalink to this headline")** - -* Draft line items or campaigns may only be converted from a `entity_status` of `DRAFT` to `PAUSED` or `ACTIVE` -* In order to activate an entire campaign (with multiple line items), each line item under the campaign, as well as the campaign itself must be set to an `entity_status` of `ACTIVE`. -* In order to change the `entity_status` of any campaign or line item, use the corresponding PUT endpoint. - -**Scheduled Tweets[¶](#scheduled-tweets "Permalink to this headline")** - -* Scheduled Tweets consist of the following new endpoints - -* Scheduled Tweets: - - * [GET accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets) - * [GET accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives#scheduled-tweets) - * [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives#post-accounts-account-id-scheduled-tweets) - * [PUT accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives#scheduled-tweet-management) - * [DELETE accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives#scheduled-tweet-management) - -* Campaign Management: - - * [GET accounts/:account\_id/scheduled\_promoted_tweets](/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets) - * [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) - * [POST accounts/:account\_id/scheduled\_promoted_tweets](/x-ads-api/campaign-management#post-accounts-account-id-scheduled-promoted-tweets) - * [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) - -* Newly scheduled Tweets can be scheduled for any date in the future -* Currently, there is no ability to preview a scheduled tweet -* Only Scheduled Tweets in the `SCHEDULED` state may be edited/deleted -* Scheduled Tweets are _not_ propagated to the enterprise Firehose, or any other data API until the `scheduled_at` date/time. - -### v1 - -Version 1 of the Ads API launched on March 31, 2016 and will reach its end of life on January 10, 2018. - -**Changes in version 1:[¶](#changes-in-version-1 "Permalink to this headline")** - -* [Versioning support](https://blog.x.com/2016/versioning-is-coming-to-twitter-s-ads-apis) -* `CUSTOM` [objective](/x-ads-api/campaign-management#objective-based-campaigns) is no longer supported -* [Batch endpoints](/x-ads-api/campaign-management#post-batch-accounts-account-id-campaigns) are now generally available -* [Reach estimate changes](https://developer.x.com/en/docs/ads/campaign-management/api-reference/reach-estimate.html#get-accounts-account-id-reach-estimate): -* To provide better reach estimation, the endpoint is now budget aware. The following parameters are now required: - * \[new\] `campaign_daily_budget_amount_local_micro` - * `currency` - * `bid` - * `objective` -* The response object has changed, and now returns ranges for response values. -* `infinite_count` has been renamed `infinite_bid_count` to avoid confusion on its purpose -* In addition to `count` and `infinite_bid_count`, these new data points will now be returned: - * `impressions` - * `engagements` - * `estimated_daily_spend_local_micro` -* Data type change for tailored audiences -* The `data_type` for Tailored Audiences has been changed from `tailored_audiences` to `tailored_audience` in all of our resposnes. -* Shared Tailored Audiences are now available as an _API-only_ beta. Shared tailored audiences allow for a single audience to be used across multiple ads accounts. Use the [POST accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions](/x-ads-api/audiences) (and related) endpoint to manage permissions of a tailored audience you would like to share across ads accounts. -* Significant improvements in how you collect performance [analytics](/x-ads-api/analytics) for advertiser accounts: -* To align with our [best practices](/x-ads-api/analytics#best-practices), we will now only allow data to be pulled for up to **7 days** of data for the [synchronous stats endpoints](/x-ads-api/analytics#get-stats-accounts-account-id). -* To simplify pulling metrics, we have replaced the `metrics` parameter with a new `metric_groups` parameter. Developers simply must request which groups of metrics they would like returned for a given request. - * Any request for metrics that are not appropriate for a given entity will be excluded from the response and represented as `null` values. _These metrics will not count against your analytics cost limit._ -* The response has been **significantly simplified**, and will now align more closely with how metrics are exposed in our UI. - * Previously we exposed a separate metric for each placement location (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, X Audience Platform). We will now return a standardized set of metrics for each (instead of `promoted_tweet_timeline_impressions`, `promoted_tweet_search_impressions`, `promoted_tweets_profile_impressions`, `promoted_tweets_tpn_impressions`), these will now be exposed when requested in one of the following categories as a single metric, `impressions` (this applies to all metrics): - * `ALL_ON_TWITTER` - * `PUBLISHER_NETWORK` - * When you make a request you’ll get a single `impressions` metric to make matching values in our UI simplier. - * You must make two queries to get both `ALL_ON_TWITTER` and `PUBLISHER_NETWORK` data, as these cannot be combined. -* [Asynchronous stats endpoints](/x-ads-api/analytics#asynchronous-analytics) are now available, based on feedback from our developers! - * A new set of endpoints to request stats _asynchronously_, for data you don’t need immediately or for historic data pulls. - * Queue a stats job using a new single endpoint. We’ll pull the data you have requested as resources allow. - * You can query a job status endpoint to determine if the data is available. - * Once the data is available, we’ll provide a pick-up ID for you to download the JSON response, which will mirror the response from the synchronous endpoint. - * Query up to **90 days** of data on up to **20 entities** in a single job. -* Take a look at our analytics v1 migration guide, which includes mapping of v0 metrics to v1 metrics -* Sandbox improvements * You may now [create multiple test ads accounts](/x-ads-api/campaign-management#post-accounts) in the Sandbox environment. * You may now create multiple funding instruments for a test ads account in the Sandbox environment only. This allows you to test on all of our funding instrument types. Previously only a `CREDIT_CARD` funding source was available to test with. * Want to test a beta feature? You can now toggle features on/off for an account in the Sandbox environment to accommodate your testing needs. - -### v0 - -Version 0 of the Ads API was officially launched on February 21, 2013 and was supported until October 31, 2016. - -All version 0 analytics endpoints are deprecated and will no longer exist after October 31, 2016. These endpoints have been replaced with 3 analytics endpoints in version 1. - -The reach estimation endpoint has new behavior in version 1. +The Ads API has resolved a display issue where, after adding Network Activation Duration targeting, th \ No newline at end of file diff --git a/x-ads-api/getting-started/increasing-access.mdx b/x-ads-api/getting-started/increasing-access.mdx index be6a30163..415fb16e7 100644 --- a/x-ads-api/getting-started/increasing-access.mdx +++ b/x-ads-api/getting-started/increasing-access.mdx @@ -1,6 +1,8 @@ --- title: Increasing access keywords: ["increase access", "upgrade access", "additional permissions", "access upgrade", "request access", "expand access"] + +description: ### Requesting additional App-level permissions If your application is limited to any of the below app-level permissions and you wish to access additional e... --- ### Requesting additional App-level permissions diff --git a/x-ads-api/getting-started/step-by-step-guide.mdx b/x-ads-api/getting-started/step-by-step-guide.mdx index c890fbd00..2bbbc4172 100644 --- a/x-ads-api/getting-started/step-by-step-guide.mdx +++ b/x-ads-api/getting-started/step-by-step-guide.mdx @@ -1,6 +1,8 @@ --- title: Step-by-step guide keywords: ["Ads API getting started", "Ads API guide", "Ads API setup", "get Ads API access", "Ads API tutorial", "Ads API quickstart"] + +description: import { Button } from "/snippets/button.mdx"; ## How to get access to the Ads API 1. Sign up for a [developer account](https://developer.x.com/en/apply-fo... --- import { Button } from "/snippets/button.mdx"; diff --git a/x-ads-api/getting-started/subscribe-for-updates.mdx b/x-ads-api/getting-started/subscribe-for-updates.mdx index f9b55c0f0..e61c58eac 100644 --- a/x-ads-api/getting-started/subscribe-for-updates.mdx +++ b/x-ads-api/getting-started/subscribe-for-updates.mdx @@ -2,4 +2,5 @@ title: Subscribe for updates url: https://developer.x.com/en/docs/x-ads-api/newsletter keywords: ["subscribe", "newsletter", "updates", "Ads API updates", "subscribe for updates", "email updates"] ---- \ No newline at end of file + +description: Reference documentation for the Subscribe for updates endpoint and related functionality.--- \ No newline at end of file diff --git a/x-ads-api/introduction.mdx b/x-ads-api/introduction.mdx index db40ee634..c00a28dbb 100644 --- a/x-ads-api/introduction.mdx +++ b/x-ads-api/introduction.mdx @@ -1,5 +1,6 @@ --- title: Introduction +description: The X Ads API enables developers to programmatically manage advertising campaigns, creatives, audiences, analytics, and conversions on X at scale. keywords: ["X Ads API", "Twitter Ads API", "advertising API", "ads platform", "campaign management", "ad campaigns", "advertising automation", "ads analytics"] --- diff --git a/x-ads-api/llms.txt b/x-ads-api/llms.txt new file mode 100644 index 000000000..e1bac36a6 --- /dev/null +++ b/x-ads-api/llms.txt @@ -0,0 +1,42 @@ +# X Ads API + + > Full reference for the X Ads API: Campaign Management, Creatives, Audiences, Analytics, Measurement, and advertising automation tools. + +## Core +- [Analytics](https://docs.x.com/x-ads-api/analytics.md): Retrieve detailed performance metrics for X ad campaigns, line items, and creatives — including impressions, e +- [Audiences](https://docs.x.com/x-ads-api/audiences.md): Create and manage Tailored Audiences and Custom Audiences using CRM lists, website visitors, mobile app users, +- [Campaign Management](https://docs.x.com/x-ads-api/campaign-management.md): Create, manage, and optimize advertising campaigns on X. Define budgets, targeting, creatives, and bidding str +- [Catalog Management](https://docs.x.com/x-ads-api/catalog-management.md): The Catalog API is a commerce solution that gives advertisers the ability to set up product feeds, group produ +- [Creatives](https://docs.x.com/x-ads-api/creatives.md): Manage promotable creatives on X including Tweets, images, GIFs, videos, and cards. Upload media and associate +- [Introduction](https://docs.x.com/x-ads-api/introduction.md): The X Ads API enables developers to programmatically manage advertising campaigns, creatives, audiences, analy +- [Tools and libraries](https://docs.x.com/x-ads-api/tools-and-libraries.md): The X teams maintain a small number of SDKs that support the Ads API. | | | |: + +## Campaign Management +- [Campaign Management API Reference](https://docs.x.com/x-ads-api/campaign-management/reference.md): Complete reference for all Campaign Management endpoints in the X Ads API — Accounts, Campaigns, Line Items, F + +## Fundamentals +- [Accessing Ads accounts](https://docs.x.com/x-ads-api/fundamentals/accessing-ads-accounts.md): There are two different types of accounts involved in using the Ads API: advertising accounts and X user accou +- [Currency](https://docs.x.com/x-ads-api/fundamentals/currency.md): The type of a currency is identified using [ISO-4217](http://en. +- [Error codes and responses](https://docs.x.com/x-ads-api/fundamentals/error-codes-and-responses.md): Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object( +- [Ads API hierarchy and terminology](https://docs.x.com/x-ads-api/fundamentals/hierarchy-and-terminology.md): To be successful on the Ads API, it’s important to understand how entities in X Ads relate to each other. This +- [Making Authenticated Requests](https://docs.x.com/x-ads-api/fundamentals/making-authenticated-requests.md): Accessing the X Ads API endpoints requires your application to send authenticated web requests securely using +- [Pagination](https://docs.x.com/x-ads-api/fundamentals/pagination.md): In order to support a larger maximum number of campaigns and efficient retrieval of all entities associated wi +- [Rate limiting](https://docs.x.com/x-ads-api/fundamentals/rate-limiting.md): The Advertiser API is rate limited similarly to REST API v1. 1, as documented here: [REST API Rate Limiting in +- [Sandbox](https://docs.x.com/x-ads-api/fundamentals/sandbox.md): The sandbox is an environment for you to test and build your Ads API implementation. Campaigns created via the +- [Sorting](https://docs.x.com/x-ads-api/fundamentals/sorting.md): Sorting is available for most Ads API collection endpoints (that return a list of objects). Depending on the e +- [Timezones](https://docs.x.com/x-ads-api/fundamentals/timezones.md): Datetime values are always returned in UTC time (as indicated by the Z at the end of the datetime value. ) Dat +- [Versions](https://docs.x.com/x-ads-api/fundamentals/versioning.md): For the most up to date information on historical versions of the X Ads API, please reference the information + +## Getting Started +- [Increasing access](https://docs.x.com/x-ads-api/getting-started/increasing-access.md): ### Requesting additional App-level permissions If your application is limited to any of the below app-level +- [Step-by-step guide](https://docs.x.com/x-ads-api/getting-started/step-by-step-guide.md): import { Button } from +- [Subscribe for updates](https://docs.x.com/x-ads-api/getting-started/subscribe-for-updates.md): Reference documentation for the Subscribe for updates endpoint and related functionality. + +## Measurement +- [AB Testing](https://docs.x.com/x-ads-api/measurement/ab-testing.md): A/B Testing allows advertisers to segment the users they're reaching on X so that they can understand how best +- [Mobile Conversions](https://docs.x.com/x-ads-api/measurement/mobile-conversions.md): X [mobile app promotion](https://biz. +- [Web conversions](https://docs.x.com/x-ads-api/measurement/web-conversions.md): * The primary requirement of Conversion API is having a [Developer Account](https://developer. + +## Agent Resources +- [AGENTS.md](https://docs.x.com/AGENTS.md) — Instructions for AI agents +- [llms-full.txt](https://docs.x.com/llms-full.txt) \ No newline at end of file diff --git a/x-ads-api/measurement/ab-testing.mdx b/x-ads-api/measurement/ab-testing.mdx index 2f330ee7d..461088e60 100644 --- a/x-ads-api/measurement/ab-testing.mdx +++ b/x-ads-api/measurement/ab-testing.mdx @@ -1,7 +1,8 @@ --- title: AB Testing keywords: ["AB testing", "A/B testing", "split testing", "ad testing", "campaign testing", "test campaigns"] ---- + +description: A/B Testing allows advertisers to segment the users they're reaching on X so that they can understand how best to optimize for campaign performance and ...--- import { Button } from '/snippets/button.mdx'; @@ -310,612 +311,4 @@ Requirements: ### Updating -Update an A/B Test using the [PUT accounts/:account\_id/ab\_tests/:ab\_test\_id](https://developer.x.com/en/docs/x-ads-api/measurement/api-reference/ab-tests) endpoint. The endpoint requires that a JSON blob be sent in the request. The Content-Type must be set to application/json. - -Like other update endpoints, the [PUT accounts/:account\_id/ab\_tests/:ab\_test\_id](/x-ads-api/measurement/ab-testing#get-accounts-account-id-ab-tests) endpoint requires that the A/B Test ID be referenced in the URL. In general, A/B Tests can only be updated while the status is SCHEDULED. There is one exception: it's possible to update the A/B Test's end_time while it's LIVE. - -This endpoint supports partial JSON with object IDs. The following principles apply: - -* To add or remove objects or elements, pass in the entire array (and its substructures); this is a **replacement** operation - -* Otherwise, modify (change, add, remove) existing _fields_ by referencing key names or IDs - - * To remove a field, set its value to null - - * Fields that are not passed in are not modified - - -For example, adding a third user group to the previously created A/B Test would require us to send the user_groups array with the two existing user group objects as well as with the new one we'd like to add. Think of this as _recreating_ the user_groups array; pass the data in as if you were creating it this way to begin with (do not pass in user group object IDs). The user_groups array in the update request could be represented as follows. - -```json -[ - { - "entity_ids": [ - "f2qcw", - "f2tht" - ], - "size": "30.0", - "name": "first group" - }, - { - "entity_ids": [ - "f2rqi", - "f2tws" - ], - "size": "30.0", - "name": "second group", - "description": "second AB test group" - }, - { - "entity_ids": [ - "i1vwr", - "i1xre" - ], - "size": "40.0" - } -] -``` - -Notice that the size values across objects still add up to 100.00. If we would not have updated them for the first two objects—previously set at 50.00 each—the request would have failed. - -If, instead, we simply wanted to add a description to the first user group, the user_groups array in the update request would be represented as follows. - -```json -[ - { - "id": "p1bcx", - "description": "updated using a PUT request" - } -] -``` - -We reference the user group object by ID and only include the field we'd like to modify. - -#### Request Examples - -This section provides additional example update requests. Think of these as being called sequentially. JSON blobs are formatted for readability. Responses are omitted. - -To make the following modifications, the request would be represented as follows. (This is the same as the previously used example above.) - -1. Adds a third user group without a name or description - -2. Changes the percentage of users in each user group - - -twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d ' -```json -twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d ' -{ - "user_groups": [ - { - "entity_ids": [ - "f2qcw", - "f2tht" - ], - "size": "30.00", - "name": "first group" - }, - { - "entity_ids": [ - "f2rqi", - "f2tws" - ], - "size": "30.00", - "name": "second group", - "description": "second AB test group" - }, - { - "entity_ids": [ - "i1vwr", - "i1xre" - ], - "size": "40.00" - } - ] -}' -``` - -To make the following modifications, the request would be represented as follows. - -1. Removes the A/B Test description - -2. Adds a description to the first user group - -3. Add an entity ID (f2syz) to the second user group - - -twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d ' -```json -twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d ' -{ - "description": null, - "user_groups": [ - { - "id": "p1bcx", - "description": "first AB test group" - }, - { - "id": "p1bcy", - "entity_ids": [ - "f2rqi", - "f2tws", - "f2syz" - ] - } - ] -}' -``` -The third modification requires that we pass in the two existing entity IDs along with the new one. Notice that no changes were made to the third user group. - -To make the following modifications, the request would be represented as follows. - -1. Removes the second user group - -2. Changes the percentage of users in each user group - - -```json -twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d ' -{ - "user_groups": [ - { - "entity_ids": [ - "f2qcw", - "f2tht" - ], - "size": "55.00", - "name": "first group" - }, - { - "entity_ids": [ - "i1vwr", - "i1xre" - ], - "size": "45.00" - } - ] -}' -``` -## API reference - -### AB Tests - -[]() - - -#### GET accounts/:account\_id/ab\_tests - -Retrieve details for some or all A/B tests. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/ab_tests` - -##### 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| ab\_test\_ids
_optional_ | Scope the response to just the desired A/B Tests by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `hr7l0` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| live_during
_optional_ | Scope the response to A/B Tests that were or that will be live during the given date range. This returns A/B Tests whose start and end times overlap—partially or fully—with the given date range.

Specify values as comma-separated dates, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). The earlier date should be specified first.

Type: string

Example: `2020-11-01T08:00:00Z,2020-12-01T08:00:00Z` | -| q
_optional_ | An optional query to scope resource by `name`. Omit this parameter to retrieve all.

Type: string

Min, Max length: `1`, `80` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.

Type: string

Example: `created_at-asc` | -| status
_optional_ | Scope the response to A/B Tests with the desired status.

Type: enum

Possible values: `COMPLETED`, `LIVE`, `SCHEDULED` | -| user_id
_optional_ | Scope the response to A/B Tests created by the specified user ID.

**Note**: Cannot be specified at the same time as `username`.

Type: long

Example: `756201191646691328. | -| username
_optional_ | Scope the response to A/B Tests created by the specified username. Do not include the leading "@" symbol.

**Note**: Cannot be specified at the same time as `user_id`.

Type: string

Example: `apimctestface. | -| 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/ab_tests` - -##### Example Response -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t" - } - }, - "data": [ - { - "created_at": "2022-05-25T00:00:00Z", - "created_by": { - "user_id": "756201191646691328", - "username": "apimctestface" - }, - "deleted": false, - "description": "documentation example", - "end_time": "2022-05-30T01:00:00Z", - "entities": [ - { - "id": "p1bcx", - "account_id": "18ce54d4x5t" - }, - { - "id": "p1bcy", - "account_id": "18ce54d4x5t" - } - ], - "entity_type": "CAMPAIGN", - "id": "hr7l0", - "name": "first AB test", - "start_time": "2022-05-25T01:00:00Z", - "status": "SCHEDULED", - "user_groups": [ - { - "id": "p1bcx", - "name": "first group", - "description": null, - "size": "50.0", - "entity_ids": [ - "f2qcw", - "f2tht" - ] - }, - { - "id": "p1bcy", - "name": "second group", - "description": "second AB test group", - "size": "50.0", - "entity_ids": [ - "f2rqi", - "f2tws" - ] - } - ], - "updated_at": "2022-05-25T00:00:00Z", - "updated_by": { - "user_id": "756201191646691328", - "username": "apimctestface" - } - } - ], - "next_cursor": null - } -``` -#### POST accounts/:account\_id/ab\_tests - -Create a new A/B Test. - -All parameters are sent in the request body and a `Content-Type` of `application/json` is required. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/ab_tests` - -##### 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| end_time
_required_ | The time, expressed in ISO 8601, that the A/B Test will end.

Type: string

Example: `2020-10-02T00:00:00Z` | -| entity_type
_required_ | The type of entity to be used for user group splits.

Type: enum

Possible values: `CAMPAIGN`, `LINE_ITEM` | -| start_time
_required_ | The time, expressed in ISO 8601, that the A/B Test will begin.

Type: string

Example: `2022-05-30T00:00:00Z` | -| user_groups
_required_ | Describes the user groups. More information in the table below. Between 2 and 30 user groups may be specified.

Type: array of objects | -| description
_optional_ | The description for the A/B Test. Maximum length: 1,024 characters.

Type: string

Example: `documentation example` | -| name
_optional_ | The name for the A/B Test. Maximum length: 255 characters.

Type: string

Example: `first AB test` | - -#### User Groups - -| Name | Description | -| :--- | :--- | -| entity_ids
_required_ | An array of entity IDs.

**Note**: Entities can only be associated with one A/B Test.

Type: array

Example: `["dxi0l", "e66bl"]` | -| size
_required_ | The percentage of users to allocate to this user group. This is a numeric value represented as a string with at most two digits after the decimal point. For example, represent 40% as either: 40, 40.0, or 40.00.

**Note**: The size values across _objects_ **must** add up to 100.00.

Type: array

Min, Max: `1.00`, `99.00` | -| description
_optional_ | The description for the user group. Maximum length: 1,024 characters.

Type: string

Example: `second AB test group` | -| name
_optional_ | The name for the user group. Maximum length: 255 characters.

Type: string

Example: `first group` | - -### Example Request - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests -d '{"end_time": "2022-05-30T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2022-05-25T01:00:00Z", "user_groups": [{"entity_ids": ["f2qcw", "f2tht"], "size": "50.00", "name": "first group"},{"entity_ids": ["f2rqi", "f2tws"], "size": "50.00", "name": "second group", "description": "second AB test group"}], "name": "first AB test", "description": "documentation example"}'` - -### Example Response -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "end_time": "2022-05-30T01:00:00Z", - "entity_type": "CAMPAIGN", - "start_time": "2022-05-25T01:00:00Z", - "user_groups": [ - { - "entity_ids": [ - "f2qcw", - "f2tht" - ], - "size": "50.0", - "name": "first group" - }, - { - "entity_ids": [ - "f2rqi", - "f2tws" - ], - "size": "50.0", - "name": "second group", - "description": "second AB test group" - } - ], - "name": "first AB test", - "description": "documentation example" - } - }, - "data": { - "created_at": "2022-05-25T00:00:00Z", - "created_by": { - "user_id": "756201191646691328", - "username": "apimctestface" - }, - "deleted": false, - "description": "documentation example", - "end_time": "2022-05-30T01:00:00Z", - "entities": [ - { - "id": "p1bcx", - "account_id": "18ce54d4x5t" - }, - { - "id": "p1bcy", - "account_id": "18ce54d4x5t" - } - ], - "entity_type": "CAMPAIGN", - "id": "hr7l0", - "name": "first AB test", - "start_time": "2022-05-25T01:00:00Z", - "status": "SCHEDULED", - "user_groups": [ - { - "id": "p1bcx", - "name": "first group", - "description": null, - "size": "50.0", - "entity_ids": [ - "f2qcw", - "f2tht" - ] - }, - { - "id": "p1bcy", - "name": "second group", - "description": "second AB test group", - "size": "50.0", - "entity_ids": [ - "f2rqi", - "f2tws" - ] - } - ], - "updated_at": "2022-05-25T00:00:00Z", - "updated_by": { - "user_id": "756201191646691328", - "username": "apimctestface" - } - } - } -``` -#### PUT accounts/:account\_id/ab\_tests/:ab\_test\_id - -Update the specified A/B Test. - -All parameters are sent in the request body and a `Content-Type` of `application/json` is required. - -This endpoint supports partial JSON with object IDs. The following principles apply: - -* To add or remove objects or elements, pass in the entire array (and its substructures); this is a **replacement** operation - * Think of this as recreating the array -* Otherwise, modify (change, add, remove) existing fields by referencing key names or IDs - * To remove a field, set its value to `null` - * Fields that are not passed in are not modified - -In general, A/B Tests can only be updated while the `status` is `SCHEDULED`. There is one exception: it's possible to update the A/B Test's `end_time` while it's `LIVE`. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| ab\_test\_id
_required_ | A reference to the A/B Test you are operating with in the request.

Type: string

Example: `hr7l0` | -| description
_optional_ | The description for the A/B Test. Maximum length: 1,024 characters.

**Note**: Can only be updated while the A/B Test `status` is `SCHEDULED`.

Type: string

Example: `documentation example` | -| end_time
_optional_ | The time, expressed in ISO 8601, that the A/B Test will end.

**Note**: Can only be updated while the A/B Test `status` is `SCHEDULED` or `LIVE`.

Type: string

Example: `2020-10-02T00:00:00Z` | -| name
_optional_ | The name for the A/B Test. Maximum length: 255 characters.

**Note**: Can only be updated while the A/B Test `status` is `SCHEDULED`.

Type: string

Example: `first AB test` | -| start_time
_optional_ | The time, expressed in ISO 8601, that the A/B Test will begin.

**Note**: Can only be updated while the A/B Test `status` is `SCHEDULED`.

Type: string

Example: `2022-05-30T00:00:00Z` | -| user_groups
_required_ | Describes the user groups. More information in the table below.

**Note**: Can only be updated while the A/B Test `status` is `SCHEDULED`.

Type: array of objects | - -#### User Groups - -| Name | Description | -| :--- | :--- | -| id
_sometimes required_ | A reference to the user group object you are operating with in the request.

**Note**: Required when modifying (changing, adding, or removing) user group object _fields_.

**Note**: Do not specify an ID when adding or removing entire user group objects.

Type: string

Example: `p1bcx` | -| description
_optional_ | The description for the user group. Maximum length: 1,024 characters.

**Note**: Unset (remove) by specifying the field with a `null` value.

Type: string

Example: `second AB test group` | -| entity_ids
_optional_ | An array of entity IDs.

**Note**: This is a replacement operation. It overwrites whatever was previously set.

**Note**: Entities can only be associated with one A/B Test.

Type: array

Example: `["dxi0l", "e66bl"]` | -| name
_optional_ | The name for the user group. Maximum length: 255 characters.

**Note**: Unset (remove) by specifying the field with a `null` value.

Type: string

Example: `first group` | -| size
_optional_ | The percentage of users to allocate to this user group. This is a numeric value represented as a string with at most two digits after the decimal point. For example, represent 40% as either: 40, 40.0, or 40.00.

**Note**: The size values across _objects_ **must** add up to 100.00.

Type: string

Min, Max: `1.00`, `99.00` | - -##### Example Request - -This request makes the following modifications. - -1. Removes the A/B Test description -2. Changes the end time -3. Adds a description to the first user group -4. Changes the percentage of users in each user group -5. Add an entity ID (`f2syz`) to the second user group - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0 -d '{"description": null, "end_time": "2022-06-01T01:00:00Z", "user_groups": [{"id": "p1bcx", "description": "first AB test group", "size": "60.00"},{"id": "p1bcy", "size": "40.00", "entity_ids": ["f2rqi", "f2tws", "f2syz"]}]}'` - -##### Example Response -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "ab_test_id": "hr7l0", - "description": null, - "end_time": "2022-06-01T01:00:00Z", - "user_groups": [ - { - "id": "p1bcx", - "description": "first AB test group", - "size": "60.0" - }, - { - "id": "p1bcy", - "size": "40.0", - "entity_ids": [ - "f2rqi", - "f2tws", - "f2syz" - ] - } - ] - } - }, - "data": { - "created_at": "2020-05-25T00:00:00Z", - "created_by": { - "user_id": "756201191646691328", - "username": "apimctestface" - }, - "deleted": false, - "description": null, - "end_time": "2022-06-01T01:00:00Z", - "entities": [ - { - "id": "p1bcx", - "account_id": "18ce54d4x5t" - }, - { - "id": "p1bcy", - "account_id": "18ce54d4x5t" - } - ], - "entity_type": "CAMPAIGN", - "id": "hr7l0", - "name": "first AB test", - "start_time": "2022-05-25T01:00:00Z", - "status": "SCHEDULED", - "user_groups": [ - { - "id": "p1bcx", - "name": "first group", - "description": "first AB test group", - "size": "60.0", - "entity_ids": [ - "f2qcw", - "f2tht" - ] - }, - { - "id": "p1bcy", - "name": "second group", - "description": "second AB test group", - "size": "40.0", - "entity_ids": [ - "f2rqi", - "f2tws", - "f2syz" - ] - } - ], - "updated_at": "2022-05-25T00:17:23Z", - "updated_by": { - "user_id": "756201191646691328", - "username": "apimctestface" - } - } - } -``` -#### DELETE accounts/:account\_id/ab\_tests/:ab\_test\_id - -Delete the specified A/B Test. - -**Note**: Deleting an A/B Test 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/ab_tests/:ab_test_id` - -##### Parameters - -| Name | Description | -| :--- | :--- | -| ab\_test\_id
_required_ | A reference to the A/B Test you are operating with in the request.

Type: string

Example: `hr7l0` | - -##### Example Request - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0` - -### Example Response -```json - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "ab_test_id": "hr7l0" - } - }, - "data": { - "created_at": "2022-05-25T00:00:00Z", - "created_by": { - "user_id": "756201191646691328", - "username": "apimctestface" - }, - "deleted": true, - "description": null, - "end_time": "2022-06-01T01:00:00Z", - "entities": [ - { - "id": "p1bcx", - "account_id": "18ce54d4x5t" - }, - { - "id": "p1bcy", - "account_id": "18ce54d4x5t" - } - ], - "entity_type": "CAMPAIGN", - "id": "hr7l0", - "name": "first AB test", - "start_time": "2022-05-25T01:00:00Z", - "status": "SCHEDULED", - "user_groups": [ - { - "id": "p1bcx", - "name": "first group", - "description": "first AB test group", - "size": "60.0", - "entity_ids": [ - "f2qcw", - "f2tht" - ] - }, - { - "id": "p1bcy", - "name": "second group", - "description": "second AB test group", - "size": "40.0", - "entity_ids": [ - "f2rqi", - "f2tws", - "f2syz" - ] - } - ], - "updated_at": "2022-06-02T00:18:31Z", - "updated_by": { - "user_id": "756201191646691328", - "username": "apimctestface" - } - } - } -``` +Update an A/B Test using the [PUT accounts/:account\_id/ab\_tests/:ab\_test\_id](https://developer.x.com/en/docs/x-ads-api/measurement/api-reference/ab-tests) endpoint. The endpoint requires that a JSON blob be sent in the request. The Content-Type \ No newline at end of file diff --git a/x-ads-api/measurement/mobile-conversions.mdx b/x-ads-api/measurement/mobile-conversions.mdx index 6cfd2823d..5a1b298fa 100644 --- a/x-ads-api/measurement/mobile-conversions.mdx +++ b/x-ads-api/measurement/mobile-conversions.mdx @@ -1,7 +1,8 @@ --- title: Mobile Conversions keywords: ["mobile conversions", "mobile conversion tracking", "app conversions", "mobile app tracking", "conversion tracking"] ---- + +description: X [mobile app promotion](https://biz.--- import { Button } from '/snippets/button.mdx'; @@ -130,7 +131,7 @@ These are what define the conversion windows set up per each conversion type for | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | app\_event\_tag_ids
_optional_ | Scope the response to just the desired app event tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `jhp` | | 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | @@ -189,7 +190,7 @@ These are what define the conversion windows set up per each conversion type for | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | | app\_event\_tag_id
_required_ | A reference to the app event tag you are operating with in the request.

Type: string

Example: `jhp` | | with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | @@ -202,568 +203,4 @@ These are what define the conversion windows set up per each conversion type for "request": { "params": { "app_event_tag_id": "jhp", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "provider_app_event_name": null, - "app_store_identifier": "co.vine.android", - "post_view_attribution_window": 1, - "deep_link_scheme": "vine://", - "id": "jhp", - "retargeting_enabled": true, - "conversion_type": "INSTALL", - "created_at": "2016-12-08T07:49:58Z", - "post_engagement_attribution_window": 14, - "provider_app_event_id": null, - "last_tracked_at": "2021-05-22T17:00:04Z", - "status": "TRACKING", - "updated_at": "2016-12-08T23:07:54Z", - "os_type": "ANDROID", - "deleted": false - } - } -``` -#### POST accounts/:account\_id/app\_event_tags - -Create a new app event tag associated with the current account. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/app_event_tags` - -##### 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| app\_store\_identifier
_required_ | The app store identifier.

Type: string

Example: `com.twitter.android` | -| conversion_type
_required_ | The type of conversion event.

Type: enum

Possible values: `ACHIEVEMENT_UNLOCKED`, `ADDED_PAYMENT_INFO`, `ADD_TO_CART`, `ADD_TO_WISHLIST`, `CHECKOUT_INITIATED`, `CONTENT_VIEW`, `INSTALL`, `INVITE`, `LEVEL_ACHIEVED`, `LOGIN`, `PURCHASE`, `RATED`, `RESERVATION`, `RE_ENGAGE`, `SEARCH`, `SHARE`, `SIGN_UP`, `SPENT_CREDITS`, `TUTORIAL_COMPLETE`, `UPDATE` | -| os_type
_required_ | The OS type for the app.

Type: enum

Possible values: `IOS`, `ANDROID` | -| provider\_app\_event_id
_required_ | The ID of the conversion tag on provider's site.

Type: string

Example: `provider_tag_j5394` | -| provider\_app\_event_name
_required_ | The name of the conversion tag on provider's site.

Type: string

Example: `provider_name_a4382` | -| deep\_link\_scheme
_optional_ | Specify the deep link URI for the app associated with this tag.

Type: string

Example: `twitter://` | -| post\_engagement\_attribution_window
_optional_ | The post-engagement attribution window for these events.

Type: int

Default: 30
Possible values: `1`, `7`, `14`, `30` | -| post\_view\_attribution_window
_optional_ | The post-view attribution window for these events.

Type: int

Default: 1
Possible values: `0`, `1`, `7`, `14`, `30` | -| retargeting_enabled
_optional_ | Specify if retargeting should be enabled for this app event tag.

Type: boolean

Default: true
Possible values: `true`, `false` | - -##### Example Request - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/app_event_tags?app_store_identifier=com.twitter.android&os_type=ANDROID&conversion_type=PURCHASE&provider_app_event_id=abc123&provider_app_event_name=test-tag` - -##### Example Response -```json - { - "data": { - "provider_app_event_name": "test-tag", - "app_store_identifier": "com.twitter.android", - "post_view_attribution_window": 1, - "deep_link_scheme": "https://", - "id": "3p3t", - "retargeting_enabled": true, - "conversion_type": "PURCHASE", - "created_at": "2017-09-06T06:58:22Z", - "post_engagement_attribution_window": 30, - "provider_app_event_id": "abc123", - "updated_at": "2017-09-06T06:58:22Z", - "os_type": "ANDROID", - "deleted": false - }, - "request": { - "params": { - "provider_app_event_name": "test-tag", - "app_store_identifier": "com.twitter.android", - "account_id": "18ce54d4x5t", - "conversion_type": "PURCHASE", - "provider_app_event_id": "abc123", - "os_type": "ANDROID" - } - } - } -``` -#### DELETE accounts/:account\_id/app\_event_tags/:id - -Delete the specified app event tag belonging to the current account. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/app_event_tags/: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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| id
_required_ | A reference to the app event tag you are operating with in the request.

Type: string

Example: `jhp` | - -##### Example Request - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/app_event_tags/jhp` - -##### Example Response -```json - { - "data": { - "provider_app_event_name": null, - "app_store_identifier": "co.vine.android", - "post_view_attribution_window": 1, - "deep_link_scheme": "vine://", - "id": "jhp", - "retargeting_enabled": true, - "conversion_type": "INSTALL", - "created_at": "2016-12-08T07:49:58Z", - "post_engagement_attribution_window": 14, - "provider_app_event_id": null, - "last_tracked_at": "2021-05-22T17:00:04Z", - "status": "TRACKING", - "updated_at": "2017-08-30T05:44:57Z", - "os_type": "ANDROID", - "deleted": true - }, - "request": { - "params": { - "id": "jhp", - "account_id": "5gvk9h" - } - } - } -``` - -### App Lists - - - -#### GET accounts/:account\_id/app\_lists - -Retrieve details for some or all app lists associated with the current account. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/app_lists` - -#### 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| app\_list\_ids
_optional_ | Scope the response to just the desired app lists by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `wm7x` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/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 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/app_lists?app_list_ids=wm7x` - -##### Example Response -```json - { - "request": { - "params": { - "app_list_ids": [ - "wm7x" - ], - "account_id": "18ce54d4x5t" - } - }, - "next_cursor": null, - "data": [ - { - "id": "wm7x", - "name": "foo @ 14026528192426843" - } - ] - } -``` -#### GET accounts/:account\_id/app\_lists/:app\_list\_id - -Retrieve a specific app list associated with the current account. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/app_lists/:app_list_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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| app\_list\_id
_required_ | A reference to the app list you are operating with in the request.

Type: string

Example: `28ukf` | -| 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/app_lists/28ukf` - -##### Example Response -```json - { - "data": { - "name": "twitter @ 262689209670784", - "id": "28ukf", - "created_at": "2017-08-17T17:07:42Z", - "updated_at": "2017-08-17T17:07:42Z", - "deleted": false, - "apps": [ - { - "app_store_identifier": "com.twitter.android", - "os_type": "Android" - } - ] - }, - "request": { - "params": { - "app_list_id": "28ukf", - "account_id": "18ce54d4x5t" - } - } - } -``` -#### POST accounts/:account\_id/app\_lists -Create an `app_list` associated with the current account. - -Currently there is a limit of 100 `app_list` objects per `account_id` and 500 apps per `app_list`. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/app_lists` - -##### 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| app\_store\_identifiers
_required_ | The app store identifiers to include in the `app_list`

Type: string

Example: `com.twitter.android` | -| name
_required_ | The name you will assign to the `app_list`

Type: string

Example: `My First App List` | - -##### Example Request - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/app_lists?name=app list&app_store_identifiers=com.twitter.android` - -##### Example Response -```json - { - "data": { - "name": "app list", - "id": "2a4um", - "created_at": "2017-09-06T07:17:26Z", - "updated_at": "2017-09-06T07:17:26Z", - "deleted": false, - "apps": [ - { - "app_store_identifier": "com.twitter.android", - "os_type": "Android" - } - ] - }, - "request": { - "params": { - "app_store_identifiers": [ - "com.twitter.android" - ], - "name": "app list", - "account_id": "18ce54d4x5t" - } - } - } -``` -#### DELETE accounts/:account\_id/app\_lists/:app\_list\_id - -Delete the specified app list associated with the current account. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/app_lists/:app_list_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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| app\_list\_id
_required_ | A reference to the app list you are operating with in the request.

Type: string

Example: `28ukf` | - -##### Example Request - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/app_lists/28ukf` - -##### Example Response -```json - { - "data": { - "name": "twitter @ 262689209670784", - "id": "28ukf", - "created_at": "2017-08-17T17:07:42Z", - "updated_at": "2017-09-12T22:20:33Z", - "deleted": true, - "apps": [ - { - "app_store_identifier": "com.twitter.android", - "os_type": "Android" - } - ] - }, - "request": { - "params": { - "app_list_id": "28ukf", - "account_id": "18ce54d4x5t" - } - } - } -``` - -### App Event Provider Configurations - -[ ❯]() - -#### GET accounts/:account\_id/app\_event\_provider\_configurations[¶](#get-accounts-account-id-app-event-provider-configurations "Permalink to this headline") - - -Retrieve details for some or all app event provider configurations (core configuration for Mobile Application Conversion Tracking) associated with the current account. - -##### Resource URL - -`https://ads-api.x.com/11/accounts/:account_id/app_event_provider_configurations` - -##### 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| ids
_optional_ | Scope the response to just the desired configurations by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `25n` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/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 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/11/accounts/18ce54d4x5t/app_event_provider_configurations?ids=25n` - -##### Example Response -```json - { - "data": [ - { - "provider_name": "Answers powered by Fabric", - "id": "25n", - "provider_advertiser_id": "54ac2766f0de9e1f7a00001a", - "created_at": "2016-12-08T07:49:58Z", - "provider_advertiser_identifier": "54ac2766f0de9e1f7a00001a", - "updated_at": "2017-05-12T21:37:15Z", - "deleted": false - } - ], - "next_cursor": null, - "request": { - "params": { - "ids": [ - "25n" - ], - "account_id": "18ce54d4x5t" - } - } - } -``` -#### GET accounts/:account\_id/app\_event\_provider\_configurations/:id - -Retrieve a specific ID for event provider configurations (core configuration for Mobile Application Conversion Tracking) associated with the current account. - -##### Resource URL - -`https://ads-api.x.com/11/accounts/:account_id/app_event_provider_configurations/: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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| id
_required_ | A reference to the app event provider configuration you are operating with in the request.

Type: string

Example: `25n` | -| 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/11/accounts/18ce54d4x5t/app_event_provider_configurations/25n` - -##### Example Response -```json - { - "data_type": "app_event_provider_configuration", - "data": { - "provider_name": "API McTestface", - "id": "25n", - "provider_advertiser_id": "123", - "created_at": "2017-03-24T22:24:56Z", - "provider_advertiser_identifier": "123", - "updated_at": "2017-03-24T22:24:56Z", - "deleted": false - }, - "request": { - "params": { - "id": "25n", - "account_id": "18ce54d4x5t" - } - } - } -``` -##### POST accounts/:account\_id/app\_event\_provider\_configurations - -Create a new app event provider configuration associated with the current account. Only one MACT provider can be associated with a particular ads account. - -##### Resource URL - -`https://ads-api.x.com/11/accounts/:account_id/app_event_provider_configurations` - -##### 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| provider\_advertiser\_id
_required_ | The advertiser's identifier from the provider's site

Type: string

Example: `client1` | - -##### Example Request - -`POST https://ads-api.x.com/11/accounts/18ce54d4x5t/app_event_provider_configurations?provider_advertiser_id=client1` - -##### Example Response -```json - { - "data": { - "provider_name": "InternalTestProvider", - "id": "e5g", - "provider_advertiser_id": "client1", - "created_at": "2017-08-30T05:40:07Z", - "provider_advertiser_identifier": "client1", - "updated_at": "2017-09-06T06:39:03Z", - "deleted": false - }, - "request": { - "params": { - "provider_advertiser_id": "client1", - "account_id": "18ce54d4x5t" - } - } - } -``` -#### DELETE accounts/:account\_id/app\_event\_provider\_configurations/:id[¶] - -Delete the specified app event provider configuration belonging to the current account. - -##### Resource URL - -`https://ads-api.x.com/11/accounts/:account_id/app_event_provider_configurations/: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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| id
_required_ | A reference to the app event provider configuration you are operating with in the request.

Type: string

Example: `e5g` | - -##### Example Request - -`DELETE https://ads-api.x.com/11/accounts/18ce54d4x5t/app_event_provider_configurations/e5g` - -##### Example Response -```json - { - "data": { - "provider_name": "InternalTestProvider", - "id": "e5g", - "provider_advertiser_id": "client1", - "created_at": "2017-08-30T05:40:07Z", - "provider_advertiser_identifier": "client1", - "updated_at": "2017-08-30T05:40:26Z", - "deleted": true - }, - "request": { - "params": { - "id": "e5g", - "account_id": "18ce54d4x5t" - } - } - } -``` - -### Conversion Attribution - - - -#### GET conversion_attribution - -Query X to check on conversion attribution without writing a conversion event. Response will indicate X attribution. - -This relates to the [POST conversion_event](https://developer.x.com/en/docs/x-ads-api/measurement/api-reference/conversion-event#post-conversion-event) endpoint. - -Either X, TAP, or no attribution will be claimed in the response. The `twitter_attribution` node will always be present and have a value of `null` when there is no X attribution and be populated as seen in the example response below. If TAP attribution is claimed a `tpn_attribution` node will be present and populated accordingly. Please refer to the [TAP overview](https://developer.x.com/en/docs/twitter-ads-api/measurement/twitter-audience-platform/overview) for more information. - -##### Resource URL - -`https://ads-api.x.com/12/conversion_attribution` - -##### Parameters - -| Name | Description | -| :--- | :--- | -| app_id
_required_ | The unique identifier with the corresponding app store.

Type: int, string

Example: `333903271`, `com.vine.android` | -| conversion_time
_required_ | The time of the conversion event in an ISO-8601 timestamp format, with milliseconds appended.

Type: string

Example: `2014-05-22T02:38:28.103Z` | -| conversion_type
_required_ | The type of conversion event.

Type: enum

Possible values: `ACHIEVEMENT_UNLOCKED`, `ADDED_PAYMENT_INFO`, `ADD_TO_CART`, `ADD_TO_WISHLIST`, `CHECKOUT_INITIATED`, `CONTENT_VIEW`, `INSTALL`, `INVITE`, `LEVEL_ACHIEVED`, `LOGIN`, `PURCHASE`, `RATED`, `RESERVATION`, `RE_ENGAGE`, `SEARCH`, `SHARE`, `SIGN_UP`, `SPENT_CREDITS`, `TUTORIAL_COMPLETE`, `UPDATE` | -| hashed\_device\_id
_required_ | The HMAC_SHA-256 hashed IDFA or AdID.

Type: string

Example: `ABCD1234XYZ` | -| os_type
_required_ | The OS type for the app.

Type: enum

Possible values: `IOS`, `ANDROID` | -| click_window
_optional_ | The click window for this event in days.

Type: int

Default: `14`
Possible values: `1`, `7`, `14`, `30` | -| extra\_device\_ids
_optional_ | A SHA256 of the SHA1 of the device ID passed in `hashed_device_id`, plus any additional hashed device IDs.

Type: string

Example: `ABCD1234XYZ`, `DCBA4321XYZ` | -| non\_twitter\_engagement_time
_optional_ | The time of the last non-twitter engagement prior to the conversion.

Type: string

Example: `2014-05-22T02:38:28.103Z` | -| non\_twitter\_engagement_type
_optional_ | The type of non-twitter engagement prior to the conversion event.

Type: enum

Possible values: `CLICK`, `VIEW` | -| view\_through\_window
_optional_ | The view through window for this event in days.

Type: int

Default: `1`
Possible values: `0`, `1`, `7`, `14`, `30` | - -##### Example Request - -`GET https://ads-api.x.com/12/conversion_attribution?app_id=333903271&os_type=IOS&hashed_device_id=ABCD1234XYZ&conversion_type=INSTALL&conversion_time=2013-04-16T07:00:00.123Z&click_window=14&view_through_window=0` - -##### Example Response -```json - { - data:{ - "app_id":"333903271", - "os_type":"IOS", - "hashed_device_id":"ABCD1234XYZ", - "conversion_type":"INSTALL", - "partner_client_id":"123abc", - "conversion_time":"2013-04-16T07:00:00.123Z", - "click_window":14, - "view_through_window":0, - "extra_device_ids":null, - "twitter_attribution":{ - "engagement_type":"VIEW", - "engagement_time":"2013-04-16T07:00:00.123Z", - "country_code":"US", - "tweet_id":"383034667764441088", - "attribution_type":"PROMOTED", - "promoted_properties":{ - "campaign_id”: “54a21", - "campaign_name":"Vine_Contest", - "line_item_id":"23ab2d4" - } - } - }, - "data_type":"conversion_attribution", - "request":{ - "params":{ - "app_id":"333903271", - "os_type":"IOS", - "hashed_device_id":"ABCD1234XYZ", - "conversion_time":"2013-04-16T07:00:00.123Z", - "conversion_type":"INSTALL", - "click_window":14, - "view_through_window":0 - } - } - } -``` + \ No newline at end of file diff --git a/x-ads-api/measurement/web-conversions.mdx b/x-ads-api/measurement/web-conversions.mdx index b7a88f6ad..5045a4c0a 100644 --- a/x-ads-api/measurement/web-conversions.mdx +++ b/x-ads-api/measurement/web-conversions.mdx @@ -1,7 +1,8 @@ --- title: Web conversions keywords: ["web conversions", "conversion tracking", "web conversion tracking", "conversions", "track conversions", "conversion API"] ---- + +description: * The primary requirement of Conversion API is having a [Developer Account](https://developer.--- import { Button } from '/snippets/button.mdx'; ## Conversion API Set Up @@ -213,579 +214,4 @@ Note that your server code may be required to implement logic outside of this re ### Testing Events and Deduplication -### Testing Events - -When your event has successfully received conversion events, within 12 to 24 hours the status of the ‘Single event web tag’ should show TRACKING upon the Conversion Tracking page of the Ads Manager.  It will not impact in-flight campaigns to send conversions via the Conversion API.  - -You may also check the analytics results of your conversion event per tag ID by: - -* Ads Manager data export ([Analytics for Website Conversion Tracking help page](https://business.x.com/en/help/campaign-measurement-and-analytics/conversion-tracking-for-websites.html)) - -* Exporting data via the Ads API (segmentation\_type=CONVERSION\_TAGS)  - - -### Duplication between Pixel and Conversion API - -If you hope to deduplicate conversions between Pixel and Conversion API requests, we have conversion\_id as the deduplication key. The deduplication only happens at the event level. In other words, to deduplicate between pixel and CAPI requests, an advertiser has to use the same event in both pixel and CAPI requests, in addition to using the same conversion\_id. Deduplication can only happen to events that are received within a 48h time frame - -## Conversion Tracking (Overview) - -### Summary - -Conversion tracking enables you to measure the number of X users that perform a desired action after viewing and engaging with your ads on X. It will provide you the capability to measure which of your campaigns drive actions such as site visits, sign ups, and purchases. This provides advertisers with the off-X measurement capabilities to understand the performance of their direct-response ads so that they can cost-effectively acquire customers. - -Using a conversion tag, advertisers can track user conversions and tie them back to ad campaigns on X. This gives them the visibility to optimize their campaigns to meet their cost-per-acquisition (CPA) goals. - -There are a variety of website actions that an advertiser can measure with conversion tracking. They can select one or more, in accordance with the action(s) they are looking to drive with their ad campaign: - -* Site visit: User visits a landing page on an advertiser’s site -* Purchase: User completes a purchase of a product or service on the advertiser’s site -* Download: User downloads a file, such as a white paper or software package, from the advertiser’s site -* Sign up: User signs up for the advertiser’s service, newsletter, or email communication -* Custom: This is a catch-all category for a custom action that does not fall into one of the categories above - -X’s conversion tracking gives advertisers a full view of conversion attribution. Compared with third-party measurement systems that clients may have been using in lieu of X’s own conversion tracking capability, such as unique click-URLs paired with third party tracking tags, X’s conversion tag offers the ability for advertiser to track conversions attributed to mid and upper funnel engagements such as Tweet expands, Retweets, favorites, replies, and follows, as well as impressions. - -### FAQ - - - First, an advertiser creates a conversion tag, which is a snippet of code provided by X, and places it on their website. The tag is now ready to measure the conversion when a user completes the given action. - -Users are then exposed to the advertiser’s ad on the X client, which leads them to the advertiser’s website and action which they have tagged. If the user completes that action during the attribution window(s) specified by the advertisers during tag setup, the tag recognizes that the user has previously interacted with a X ad. The tag then “fires,” or sends a notification to X’s servers so that the conversion can be attributed to the ad which generated conversion. - - -No, our product is not set up to attach specific conversion tags to specific campaigns. Rather, once a tag is set up, the system automatically keeps track of which ad drove to conversions on a certain tag. - - -Default post-view attribution window: 1 day - -Default post-engagement attribution: 14 days - -These defaults can be changed during conversion tag setup or any time after the tag created. The options for post-engagement attribution windows are 1, 7, 14, 30, 60, and 90 days. The options for post-view attribution windows are none, 1, 7, 14, 30, 60, and 90 days. - - -While each client’s goals, situation, and strategies are different, here are some ideas that have worked for clients who participated in the conversion tracking alpha or beta: - -**Creative:** - -* **Offers**: Pair a discount, promotion, or free shipping offer with the Promoted Tweet to garner more interest in the action -* **Sweepstakes and contests**: Especially for well-known brands, sweepstakes and contests drove conversions -* **Tweet copy experimentation**: Testing all caps vs lower case (FREE vs free or NOW vs now) -* **Deadlines**: Offer a deadline to encourage people to take immediate action (Offer Expires December 12!) -* **Adding compelling photos**: It is worthwhile to test whether visually compelling photos to Tweet creative are effective in driving conversions; results may vary or be specific to client offering. - -**Targeting:** - -* @handle targeting and interest category targeting: Tight alignment of the Tweet copy and @handles to the intended audience of the Tweet drove conversions -* Using niche but high volume keywords: In the concert space, using keywords related to the artist/musician (e.g. their name) proved effective. -* Tailored audiences: Clients using TA web and conversion tracking together drove lower CPAs than control groups using other targeting - -The more granular your campaign segmentation, the more actionable your reported conversion results will be. For example, it is much easier to optimize a campaign with 4 keywords than optimizing a campaign with 50. - - - - -## Troubleshooting and Support for Conversion API - -For questions about error codes after calling the API, please see the section below. For all the other questions,  please do not hesitate to reach out to your Twitter representative and we will work on resolving them as soon as possible.  - -### Error Handling and Explanation - -A single request will only be successful when there are zero errors for all conversions contained within it. In the case of any error within an individual conversion, the endpoint will emit a list of all applicable errors. - -### X Ads API Error Codes Overview - -Here is an overall comprehensive list of error codes in Ads API: - -[https://developer.x.com/en/docs/twitter-ads-api/response-codes](https://developer.x.com/en/docs/twitter-ads-api/response-codes) - -Successful Conversion API responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object requested. - -#### **When there is a 500-series HTTP code**, it’s related to a server issue instead of your request or account set up. Please check the [X API status page](https://api.twitterstat.us/) or the [developer community forum](https://devcommunity.x.com/) in case others are having similar issues. - -#### When there is a 400-series HTTP code, the common cases are  - -* 400 Bad Request (request doesn’t fit standards) - -* 401 Unauthorized (authentication issues) - -* 403 Forbidden (API access issues associated with that Developer Account) - -* 404 Not Found (URL or params might not be correct for the endpoint) - - -### Conversion API error codes - -#### 400 Bad Request Scenarios - -| **Reason** | **Type** | **Error Message** | -| :--- | :--- | :--- | -| Missing Identifier Error (currently hashed email or X click ID - twclid) | 400 Bad Request | At least one user identifier must be provided | -| Invalid hashed email | 400 Bad Request | Hashed_email is not a valid SHA-256 hash | -| The type of event_id is not a single event tag (SET) | 400 Bad Request | Event\_id (<event\_id>) is not a single event tag (SET) | -| Requested conversion events exceed the limit (currently 500 events per request) | 400 Bad Request | Conversion count limit is 500 | -| Missing Event ID | 400 Bad Request | Event ID was not found | - -#### JSON Error Code Example - -##### Request: - -`POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dkt", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json` - -#### Error message: - -`{"errors":[{"code":"INVALID_PARAMETER","message":"event_id (o6dkt) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce552mlaq"}}}` -#### Request: -`twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json' ` - -#### Error message: - -`{"errors":[{"code":"INVALID_PARAMETER","message":"At least one user identifier must be provided","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}` - -#### Request: - -`twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"hashed_email": "abc"}]}]}' --header 'Content-Type: application/json'` - -#### Error message: - -`{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) is not a valid SHA-256 hash","parameter":"hashed_email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}` - -#### Request: - -`twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603", "event_id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'` - -#### Error message:  - -`{"errors":[{"code":"INVALID_PARAMETER","message":"Expected Time in yyyy-MM-ddTHH:mm:ss.SSSZ, got \"2022-06-16T01:14:00.603\" for conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}` - - -### 401 Unauthorized - -**Reason**: Authentication credentials missing or incorrect  - -**Solution**: Follow the authentication steps in the [Set Up documentation](https://developer.x.com/en/docs/twitter-ads-api/measurement/guides/conversion-api) using one of the 3 authentication methods: - -User Access Tokens for user handles other than the handle owning the Ads API application must be generated with a 3-legged OAuth flow. Options for generating the Access Token with 3-legged OAuth include - -* [Command Line with Web-based Authorization via twurl utility](https://github.com/twitter/twurl#getting-started) - -* [Command Line with PIN-based Authorization](https://developer.x.com/resources/fundamentals/authentication/pin-based-oauth) - -* [Custom web flow implementing the 3-legged OAuth pattern](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens) - - -Any user tokens used with the Conversion API must be for users with AD\_MANAGER or ACCOUNT\_ADMIN access level*, which can be checked via the [authenticated\_user\_access](https://developer.x.com/en/docs/twitter-ads-api/campaign-management/api-reference/authenticated-user-access) endpoint. - -### 403 Access Forbidden  - -| Reason | Type | Error Message | -| :--- | :--- | :--- | -| The developer account you're using does not have Ads API Access. [Apply for access here](https://developer.x.com/en/docs/twitter-ads-api/apply). | 403 Unauthorized Client | The client application with id <> making this request does not have access to X Ads API. Ensure your application has advertiser-api access. Use 'twurl accounts' and 'twurl set default \ \' to change the application you're using. | - -### 404 Not Found  - -| Reason | Type | Error Message | -| :--- | :--- | :--- | -| The request URL or params is not correct for the endpoint | 404 Route Not Found | The requested resource could not be found | -| You do not have access to the account that owns the pixel_id/Universal website tag | 404 Not Found | User <user\_id> does not have access to account <account\_id>. Type 'sn <user_id>’ to get the handle of the user. Use 'twurl accounts' and 'twurl set default \\u003Cusername\\u003E' to change the user you're using. | -| The event id does not belong to the provided account associated with the pixel ID (UWT ID) | 404 Not Found | event\_id <event\_id> does not belong to provided account | - -### JSON Error Code Example - -#### Request: - -`twurl_ads -X POST '/11/measurement/conversions/o8z6j' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'` - -**Error message:** - -`{"errors":[{"code":"NOT_FOUND","message":"event_id (abc) does not belong to provided account","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}` - -## API reference index - -For the complete API reference, select an endpoint from the list: - - -### Web Conversions - -| | | -| :--- | :--- | -| Conversion API | [measurement/conversions/:pixel_id](https://developer.x.com/en/docs/x-ads-api/measurement/web-conversions/api-reference/conversions) | -| Web Event Tag | [accounts/:account\_id/web\_event_tags](https://developer.x.com/en/docs/x-ads-api/measurement/web-conversions/api-reference/web-event-tags) | - -### Web Conversions - - - -`POST version/measurement/conversions/:pixel_id` - -Send website conversion events for a single Event Tag ID. - -The response code should be checked for success (HTTP 200 OK). It is recommended to have a retry mechanism and basic logging in place in case error codes are returned. - -The rate limit will be 100,000 request per 15 minute interval per account (each request allows 500 events). - -##### Resource URL - -`https://ads-api.x.com/12/measurement/conversions/:pixel_id` - -##### Request URL Parameters - -| Name | Description | -| :--- | :--- | -| pixel_id
_required_ | The Base Tag ID for an ad account. This represents that base36 encoded value for an ad account’s Base Tag ID.

Type: string

Example: `o8z6j` | -| conversions
_required_ | The object in POST body of the API request. List of conversion events. Up to 500 conversion events may be provided. See the table below for supported fields.

Type: array

Example: `"conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]` | - -###### conversions object - -| Name | Description | -| :--- | :--- | -| conversion_time
_required_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

Type: string

Example: `2017-10-05T00:00:00Z` | -| event_id
_required_ | The base-36 ID of a specific event. It matches a pre-configured event contained within this ad account. This is called ID in the corresponding event in Events Manager.

Type: string

Example: `o87ne` or `tw-o8z6j-o87ne` (`tw-pixel_id-event-id`) both accepted | -| identifiers
_required_ | A list of identifier objects to match the conversion event to. Supported fields are listed in a table below. At least one of the identifier objects is required.

If using IP address or user agent, a second identifier must be sent for proper conversion matching.

Type: array

Example: `"identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]` | -| number_items
_optional_ | The number of items being purchased in the event. Must be a positive number greater than zero.

Type: integer

Example: `4` | -| price_currency
_optional_ | The currency of items being purchased in the event, expressed in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217). See [Currency](https://developer.x.com/en/docs/twitter-ads-api/currency) for detailed information.

Type: string

Default: `USD`

Example: `JPY` | -| value
_optional_ | The price value of items being purchased in the event, represented in `price_currency` currency.

Type: double

Example: `100.00` | -| conversion_id
_optional_ | For deduplication between pixel and conversion API conversions. An identifier for a conversion event that can be used for de-duplication between Web Pixel and Conversion API conversions in the _same event tag_. See the [Conversions Guide](https://developer.x.com/en/docs/twitter-ads-api/measurement/guides/conversion-api)'s Testing Events and Deduplication section for more information.

Type: string

Example: `23294827` | -| description
_optional_ | Description with any additional information on the conversions.

Type: string

Example: `test conversion` | -| contents
_optional_ | List of details relating to a specific product/content to provide granular information. See table below for supported fields.

Type: array

Example: `contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content_id": "2"}]` | - -###### identifiers object - -| Name | Description | -| :--- | :--- | -| ********twclid********
_sometimes required_ | Click ID as parsed from the click-through URL. It's required if no other identifier is added.

Type: string

Example: `26l6412g5p4iyj65a2oic2ayg2` | -| ********hashed_email********
_sometimes required_ | An email address hashed with [SHA256](https://en.wikipedia.org/wiki/SHA-2). The text must be lowercase, remove any trailing or leading spaces before hashing. It's required if no other identifier is added.

Type: string

Example: For `test-email@test.com` = `e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8` | -| ********hashed\_phone\_number********
_sometimes required_ | A phone number with [E164](https://en.wikipedia.org/wiki/E.164) format and hashed with [SHA256](https://en.wikipedia.org/wiki/SHA-2). The phone number must be in E164 format before hashing. It's required if no other identifier is added.

Type: string

Example: For `+11234567890` = `1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231 ` | -| **ip_address**
_sometimes required_ | This value is written in dotted-decimal notation, with four numbers separated by periods.

IP address is required to be passed in conjunction with another identifier (twclid, email address, phone number or user agent).

Type: string

Example: 8.25.197.25 | -| **user_agent **
_sometimes required_ | This identifier allows the server to identify the application, operating system, vendor, and/or version of the requesting user agent.

User Agent is required to be passed in conjunction with another identifier (twclid, email address, phone number or IP address).

Type: string

Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10\_15\_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36. | - -###### contents object - -| Name | Description | -| :--- | :--- | -| content_id
_optional_ | SKU or GTIN; identifier that represents the content.

Type: string

Example: `jhp` | -| content\_group\_id
_optional_ | ID associated with a group of product variants

Type: integer

Example: `group 1` | -| content_name
_optional_ | Name of the product or service.

Type: string

Example: `radio flyer` | -| content_price
_optional_ | Price of the product or service.

Type: double

Example: `5.00` | -| content_type
_optional_ | Category for the product that was purchased.

Type: string

Example: `clothes` | -| num_items
_optional_ | Number of products purchased

Type: integer

Example: `1` | - -##### Response Parameters -| Name | Description | -| :--- | :--- | -| conversions_processed | Number of conversions successfully processed

Type: integer

Example: `1` | -| debug_id | A debug UUID that can be used for subsequent investigations

Type: string

Example: `ff02e052-36e4-47d6-bdf0-6d8986446562` | - -##### Example Request - -```json - twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data ' - { - "conversions":[ - { - "conversion_time":"2022-02-18T01:14:00.603Z", - "event_id":"ol288", - "identifiers":[ - { - "twclid":"23opevjt88psuo13lu8d020qkn" - }, - { - "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62" - }, - { - "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231" - }, - { - "ip_address":"1.0.0.0", - "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36" - } - ], - "value":"20.00", - "number_items":3, - "conversion_id":"23294827", - "description":"Pet supply purchases", - "contents":[ - { - "content_id":"1", - "content_name":"Blankets", - "content_type":"Pet supplies", - "content_price":100.99, - "num_items":1, - "content_group_id":"123" - } - ] - } - ] - }' --header 'Content-Type: application/json' -``` - -##### Example Request -```json - { - "request":{ - "params":{ - "account_id":"18ce552mlaq" - } - }, - "data":{ - "conversions_processed":1, - "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562" - } - } -``` - -### Web Event Tags - - -`GET accounts/:account_id/web_event_tags` - -Retrieve details for some or all web event tags associated with the current account. - -#### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/web_event_tags` - -#### 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.

Type: string

Example: `created_at-asc` | -| web\_event\_tag_ids
_optional_ | Scope the response to just the desired web event tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `o3bk1` | -| 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 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/web_event_tags?web_event_tag_ids=o3bk1` - -#### Example Response -```json - { - "request": { - "params": { - "web_event_tag_ids": [ - "o3bk1" - ], - "account_id": "18ce54d4x5t" - } - }, - "next_cursor": null, - "data": [ - { - "name": "web event tag", - "view_through_window": 7, - "click_window": 7, - "embed_code": "", - "id": "o3bk1", - "retargeting_enabled": false, - "last_tracked_at": "2021-05-22T17:00:04Z", - "status": "TRACKING", - "type": "DOWNLOAD", - "website_tag_id": "ny3od", - "deleted": false - } - ] - } -``` -#### GET accounts/:account\_id/web\_event\_tags/:web\_event\_tag\_id - -Retrieve a specific web event tag associated with the current account. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| web\_event\_tag_id
_required_ | A reference to the web event tag you are operating with in the request.

Type: string

Example: `o3bk1` | -| 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/web_event_tags/o3bk1` - -##### Example Response -```json - { - "request": { - "params": { - "web_event_tag_id": "o3bk1", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "name": "web event tag", - "view_through_window": 7, - "click_window": 7, - "embed_code": "", - "id": "o3bk1", - "retargeting_enabled": false, - "last_tracked_at": "2021-05-22T17:00:04Z", - "status": "TRACKING", - "type": "DOWNLOAD", - "website_tag_id": "ny3od", - "deleted": false - } - } -``` -#### POST accounts/:account\_id/web\_event_tags - -Create a new web event tag associated with the current account. - -#### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/web_event_tags` - -#### 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| click_window
_required_ | The click window for this web tag.

**Note**: Only the possible values listed below are accepted.

Type: int

Possible values: `1`, `7`, `14`, `30` | -| name
_required_ | The name of the web tag.

Type: string

Example: `Sample single conversion event` | -| retargeting_enabled
_required_ | Indicates if retargeting should be enabled for this web tag.

Type: boolean

Possible values: `true`, `false` | -| type
_required_ | The type of web tag.

Type: enum

Possible values: `ADDED_PAYMENT_INFO`, `ADD_TO_CART`, `ADD_TO_WISHLIST`, `CHECKOUT_INITIATED`, `CONTENT_VIEW`, `CUSTOM`, `DOWNLOAD`, `PRODUCT_CUSTOMIZATION`,`PURCHASE`, `SEARCH`, `SIGN_UP`, `SITE_VISIT`, `START_TRIAL`, `SUBSCRIBE`

(On UI, `SITE_VISIT` is shown as “Page view” and `SIGN_UP` is shown as “Lead”) | -| view\_through\_window
_required_ | The view through window for this web tag. This value must always be less than or equal to the `click_window` value.

**Note**: Only the possible values listed below are accepted.

Type: int

Possible values: `0`, `1`, `7`, `14`, `30` | - -##### Example Request - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?click_window=7&name=web event tag&retargeting_enabled=false&type=SITE_VISIT&view_through_window=7` - -#### Example Response -```json - { - "data": { - "name": "web event tag", - "view_through_window": 7, - "click_window": 7, - "embed_code": "", - "id": "o3bk1", - "retargeting_enabled": false, - "last_tracked_at": null, - "status": "UNVERIFIED", - "type": "SITE_VISIT", - "website_tag_id": "ny3od", - "deleted": false - }, - "request": { - "params": { - "name": "web event tag", - "view_through_window": 7, - "click_window": 7, - "retargeting_enabled": false, - "account_id": "18ce54d4x5t", - "type": "SITE_VISIT" - } - } - } -``` -#### PUT accounts/:account\_id/web\_event\_tags/:web\_event\_tag\_id - -Update a web event tag associated with the current account. - -##### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| web\_event\_tag_id
_required_ | The identifier for a web tag on the current account.

Type: string

Example: `o3bk1` | -| click_window
_optional_ | The click window for this web tag.

**Note**: Only the possible values listed below are accepted.

Type: int

Possible values: `1`, `7`, `14`, `30` | -| name
_optional_ | The name of the web tag.

Type: string

Example: `Sample single conversion event` | -| retargeting_enabled
_optional_ | Indicates if retargeting should be enabled for this web tag.

Type: boolean

Possible values: `true`, `false` | -| type
_optional_ | The type of web tag.

Type: enum

Possible values: Possible values: `ADDED_PAYMENT_INFO`, `ADD_TO_CART`, `ADD_TO_WISHLIST`, `CHECKOUT_INITIATED`, `CONTENT_VIEW`, `CUSTOM`, `DOWNLOAD`, `PRODUCT_CUSTOMIZATION`,`PURCHASE`, `SEARCH`, `SIGN_UP`, `SITE_VISIT`, `START_TRIAL`, `SUBSCRIBE`

(On UI, `SITE_VISIT` is shown as “Page view” and `SIGN_UP` is shown as “Lead”) | -| view\_through\_window
_optional_ | The view through window for this web tag. This value must always be less than or equal to the `click_window` value.

**Note**: Only the possible values listed below are accepted.

Type: int

Possible values: `0`, `1`, `7`, `14`, `30` | - -#### Example Request - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1?type=DOWNLOAD` - -#### Example Response -```json - { - "data": { - "name": "web event tag", - "view_through_window": 7, - "click_window": 7, - "embed_code": "", - "id": "o3bk1", - "retargeting_enabled": false, - "last_tracked_at": "2021-05-22T17:00:04Z", - "status": "UNVERIFIED", - "type": "DOWNLOAD", - "website_tag_id": "ny3od", - "deleted": false - }, - "request": { - "params": { - "web_event_tag_id": "o3bk1", - "type": "DOWNLOAD", - "account_id": "18ce54d4x5t" - } - } - } -``` -#### DELETE accounts/:account\_id/web\_event\_tags/:web\_event\_tag\_id - -Delete a specific web event tag associated to the current account. - -#### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| web\_event\_tag_id
_required_ | The identifier for a web tag on the current account.

Type: string

Example: `o3bk1` | - -##### Example Request - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1` - -##### Example Response -```json - { - "data": { - "name": "web event tag", - "view_through_window": 7, - "click_window": 7, - "embed_code": "", - "id": "o3bk1", - "retargeting_enabled": false, - "last_tracked_at": "2021-05-22T17:00:04Z", - "status": "UNVERIFIED", - "type": "DOWNLOAD", - "website_tag_id": "ny3od", - "deleted": true - }, - "request": { - "params": { - "web_event_tag_id": "o3bk1", - "account_id": "18ce54d4x5t" - } - } - } -``` +### Test \ No newline at end of file diff --git a/x-ads-api/tools-and-libraries.mdx b/x-ads-api/tools-and-libraries.mdx index 601d231b3..af20f8277 100644 --- a/x-ads-api/tools-and-libraries.mdx +++ b/x-ads-api/tools-and-libraries.mdx @@ -1,6 +1,8 @@ --- title: Tools and libraries keywords: ["Ads API tools", "Ads API libraries", "Ads API SDK", "advertising tools", "Ads API client libraries", "advertising SDK"] + + --- ## Official tools and libraries diff --git a/x-api/account-activity/create-replay-job.mdx b/x-api/account-activity/create-replay-job.mdx index 5ea81d60f..cca4780f5 100644 --- a/x-api/account-activity/create-replay-job.mdx +++ b/x-api/account-activity/create-replay-job.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/account_activity/replay/webhooks/{webhook_id}/subscriptions/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/account-activity/create-subscription.mdx b/x-api/account-activity/create-subscription.mdx index b9c8294ba..6a19077fe 100644 --- a/x-api/account-activity/create-subscription.mdx +++ b/x-api/account-activity/create-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/account_activity/webhooks/{webhook_id}/subscriptions/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/account-activity/delete-subscription.mdx b/x-api/account-activity/delete-subscription.mdx index 9a35c11dd..6d0336df3 100644 --- a/x-api/account-activity/delete-subscription.mdx +++ b/x-api/account-activity/delete-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/account_activity/webhooks/{webhook_id}/subscriptions/{user_id}/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/account-activity/get-subscription-count.mdx b/x-api/account-activity/get-subscription-count.mdx index a4969e513..ae4d0fac5 100644 --- a/x-api/account-activity/get-subscription-count.mdx +++ b/x-api/account-activity/get-subscription-count.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/account_activity/subscriptions/count ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/account-activity/get-subscriptions.mdx b/x-api/account-activity/get-subscriptions.mdx index de6879cf8..943215d43 100644 --- a/x-api/account-activity/get-subscriptions.mdx +++ b/x-api/account-activity/get-subscriptions.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/account_activity/webhooks/{webhook_id}/subscriptions/all/list ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/account-activity/migrate/overview.mdx b/x-api/account-activity/migrate/overview.mdx index f4afbe06a..6b909819e 100644 --- a/x-api/account-activity/migrate/overview.mdx +++ b/x-api/account-activity/migrate/overview.mdx @@ -1,7 +1,7 @@ --- title: v2 Account Activity API Migration Guide keywords: ["Account Activity API migration", "AAA migration", "v2 migration", "API migration guide", "migrate to v2", "Account Activity API v2"] ---- + This guide helps you migrate from the legacy Enterprise Account Activity API to the V2 Account Activity API. The core functionality remains the same, but endpoint structures and authentication methods have been updated for consistency with X API v2. diff --git a/x-api/account-activity/validate-subscription.mdx b/x-api/account-activity/validate-subscription.mdx index 5075d8cbc..62afd3ffe 100644 --- a/x-api/account-activity/validate-subscription.mdx +++ b/x-api/account-activity/validate-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/account_activity/webhooks/{webhook_id}/subscriptions/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/activity/activity-stream.mdx b/x-api/activity/activity-stream.mdx index 5eb88014e..f519b9fb6 100644 --- a/x-api/activity/activity-stream.mdx +++ b/x-api/activity/activity-stream.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/activity/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/activity/create-x-activity-subscription.mdx b/x-api/activity/create-x-activity-subscription.mdx index f11274f91..5fbf86d57 100644 --- a/x-api/activity/create-x-activity-subscription.mdx +++ b/x-api/activity/create-x-activity-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/activity/subscriptions ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/activity/delete-x-activity-subscriptions-by-ids.mdx b/x-api/activity/delete-x-activity-subscriptions-by-ids.mdx index dbbe4d42d..5ae12b347 100644 --- a/x-api/activity/delete-x-activity-subscriptions-by-ids.mdx +++ b/x-api/activity/delete-x-activity-subscriptions-by-ids.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/activity/subscriptions ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/activity/deletes-x-activity-subscription.mdx b/x-api/activity/deletes-x-activity-subscription.mdx index ffd6ddf01..05e059cbc 100644 --- a/x-api/activity/deletes-x-activity-subscription.mdx +++ b/x-api/activity/deletes-x-activity-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/activity/subscriptions/{subscription_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/activity/get-x-activity-subscriptions.mdx b/x-api/activity/get-x-activity-subscriptions.mdx index 8de76f510..a103bfb42 100644 --- a/x-api/activity/get-x-activity-subscriptions.mdx +++ b/x-api/activity/get-x-activity-subscriptions.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/activity/subscriptions ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/activity/introduction.mdx b/x-api/activity/introduction.mdx index 045cb83d4..308b9ec34 100644 --- a/x-api/activity/introduction.mdx +++ b/x-api/activity/introduction.mdx @@ -2,6 +2,8 @@ title: Introduction sidebarTitle: Introduction keywords: ["activity API", "X Activity API", "activity events", "profile updates", "user activity", "real-time events", "activity stream"] + +description: import { Button } from '/snippets/button.mdx'; The X Activity API (XAA) endpoint group allows developers to tap in to activity events happening on the X Pla... --- import { Button } from '/snippets/button.mdx'; @@ -133,24 +135,4 @@ The X Activity API has different subscription limits based on your account tier: | Method | Endpoint | Description | |:-------|:---------|:------------| | GET | [`/2/activity/stream`](/x-api/activity/activity-stream) | Connect to activity stream | -| POST | [`/2/activity/subscriptions`](/x-api/activity/create-x-activity-subscription) | Create a subscription | -| GET | [`/2/activity/subscriptions`](/x-api/activity/get-x-activity-subscriptions) | List subscriptions | -| PUT | [`/2/activity/subscriptions/:id`](/x-api/activity/update-x-activity-subscription) | Update a subscription | -| DELETE | [`/2/activity/subscriptions/:id`](/x-api/activity/deletes-x-activity-subscription) | Delete a subscription | - - -**Account setup** - -To access these endpoints, you will need: - -* An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info). -* To authenticate using the keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/projects). - -Learn more about getting access to the X API v2 endpoints in our [getting started guide](/x-api/getting-started/getting-access). - - -
- -
+| POST | [`/2/activity/subscriptions`](/x-api/activity/create-x-activity-subs \ No newline at end of file diff --git a/x-api/activity/update-x-activity-subscription.mdx b/x-api/activity/update-x-activity-subscription.mdx index df57b27e6..89a25c021 100644 --- a/x-api/activity/update-x-activity-subscription.mdx +++ b/x-api/activity/update-x-activity-subscription.mdx @@ -1,3 +1,4 @@ --- openapi: put /2/activity/subscriptions/{subscription_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/bookmarks/create-bookmark.mdx b/x-api/bookmarks/create-bookmark.mdx index 7474d20cd..62cbefe9a 100644 --- a/x-api/bookmarks/create-bookmark.mdx +++ b/x-api/bookmarks/create-bookmark.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/bookmarks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/bookmarks/delete-bookmark.mdx b/x-api/bookmarks/delete-bookmark.mdx index 78d0e4078..22457d0af 100644 --- a/x-api/bookmarks/delete-bookmark.mdx +++ b/x-api/bookmarks/delete-bookmark.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/bookmarks/{tweet_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/bookmarks/get-bookmark-folders.mdx b/x-api/bookmarks/get-bookmark-folders.mdx index dfdfbee9c..f58360b6f 100644 --- a/x-api/bookmarks/get-bookmark-folders.mdx +++ b/x-api/bookmarks/get-bookmark-folders.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks/folders ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/bookmarks/get-bookmarks-by-folder-id.mdx b/x-api/bookmarks/get-bookmarks-by-folder-id.mdx index 98c7e3b07..6f0d421f4 100644 --- a/x-api/bookmarks/get-bookmarks-by-folder-id.mdx +++ b/x-api/bookmarks/get-bookmarks-by-folder-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks/folders/{folder_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/bookmarks/get-bookmarks.mdx b/x-api/bookmarks/get-bookmarks.mdx index fc3894243..e1367873c 100644 --- a/x-api/bookmarks/get-bookmarks.mdx +++ b/x-api/bookmarks/get-bookmarks.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/add-members-to-a-chat-group-conversation.mdx b/x-api/chat/add-members-to-a-chat-group-conversation.mdx index f00d92fb1..8fb7a1c1e 100644 --- a/x-api/chat/add-members-to-a-chat-group-conversation.mdx +++ b/x-api/chat/add-members-to-a-chat-group-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/members ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/add-public-key.mdx b/x-api/chat/add-public-key.mdx index 223225bec..e1e74153f 100644 --- a/x-api/chat/add-public-key.mdx +++ b/x-api/chat/add-public-key.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/public_keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/append-chat-media-upload.mdx b/x-api/chat/append-chat-media-upload.mdx index 30258a57b..c39a26f0e 100644 --- a/x-api/chat/append-chat-media-upload.mdx +++ b/x-api/chat/append-chat-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/media/upload/{id}/append ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/create-chat-group-conversation.mdx b/x-api/chat/create-chat-group-conversation.mdx index e6763a951..5c9da9d7d 100644 --- a/x-api/chat/create-chat-group-conversation.mdx +++ b/x-api/chat/create-chat-group-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/group ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/download-chat-media.mdx b/x-api/chat/download-chat-media.mdx index 262e4eb51..87b77539b 100644 --- a/x-api/chat/download-chat-media.mdx +++ b/x-api/chat/download-chat-media.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/chat/media/{id}/{media_hash_key} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/finalize-chat-media-upload.mdx b/x-api/chat/finalize-chat-media-upload.mdx index 266930c8d..e621e12e3 100644 --- a/x-api/chat/finalize-chat-media-upload.mdx +++ b/x-api/chat/finalize-chat-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/media/upload/{id}/finalize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/get-chat-conversation.mdx b/x-api/chat/get-chat-conversation.mdx index 1e027d6c8..d9c722fc4 100644 --- a/x-api/chat/get-chat-conversation.mdx +++ b/x-api/chat/get-chat-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/chat/conversations/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/get-chat-conversations.mdx b/x-api/chat/get-chat-conversations.mdx index a7a127f69..e40d59158 100644 --- a/x-api/chat/get-chat-conversations.mdx +++ b/x-api/chat/get-chat-conversations.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/chat/conversations ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/get-user-public-keys.mdx b/x-api/chat/get-user-public-keys.mdx index 804e1cbc7..b20716f9a 100644 --- a/x-api/chat/get-user-public-keys.mdx +++ b/x-api/chat/get-user-public-keys.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/public_keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/initialize-chat-group.mdx b/x-api/chat/initialize-chat-group.mdx index 6d33f4cd5..d2ce8cb39 100644 --- a/x-api/chat/initialize-chat-group.mdx +++ b/x-api/chat/initialize-chat-group.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/group/initialize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/initialize-chat-media-upload.mdx b/x-api/chat/initialize-chat-media-upload.mdx index 763d9aca7..4dd0163ff 100644 --- a/x-api/chat/initialize-chat-media-upload.mdx +++ b/x-api/chat/initialize-chat-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/media/upload/initialize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/initialize-conversation-keys.mdx b/x-api/chat/initialize-conversation-keys.mdx index 455ca4998..3da9a1a16 100644 --- a/x-api/chat/initialize-conversation-keys.mdx +++ b/x-api/chat/initialize-conversation-keys.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/mark-conversation-as-read.mdx b/x-api/chat/mark-conversation-as-read.mdx index 40f028eb7..167bcec5f 100644 --- a/x-api/chat/mark-conversation-as-read.mdx +++ b/x-api/chat/mark-conversation-as-read.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/read ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/send-chat-message.mdx b/x-api/chat/send-chat-message.mdx index b5c2693a1..54bae281f 100644 --- a/x-api/chat/send-chat-message.mdx +++ b/x-api/chat/send-chat-message.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/messages ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/chat/send-typing-indicator.mdx b/x-api/chat/send-typing-indicator.mdx index 79b77242f..905dc52be 100644 --- a/x-api/chat/send-typing-indicator.mdx +++ b/x-api/chat/send-typing-indicator.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/chat/conversations/{id}/typing ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/communities/get-community-by-id.mdx b/x-api/communities/get-community-by-id.mdx index 2670fff6d..6644a4ed9 100644 --- a/x-api/communities/get-community-by-id.mdx +++ b/x-api/communities/get-community-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/communities/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/communities/search-communities.mdx b/x-api/communities/search-communities.mdx index 28faf05a7..1e3761464 100644 --- a/x-api/communities/search-communities.mdx +++ b/x-api/communities/search-communities.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/communities/search ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/community-notes/create-a-community-note.mdx b/x-api/community-notes/create-a-community-note.mdx index 09a19080d..787a19c20 100644 --- a/x-api/community-notes/create-a-community-note.mdx +++ b/x-api/community-notes/create-a-community-note.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/notes ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/community-notes/delete-a-community-note.mdx b/x-api/community-notes/delete-a-community-note.mdx index 847876e9f..1594a3d0f 100644 --- a/x-api/community-notes/delete-a-community-note.mdx +++ b/x-api/community-notes/delete-a-community-note.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/notes/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/community-notes/evaluate-a-community-note.mdx b/x-api/community-notes/evaluate-a-community-note.mdx index 547580179..b1c59ddc0 100644 --- a/x-api/community-notes/evaluate-a-community-note.mdx +++ b/x-api/community-notes/evaluate-a-community-note.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/evaluate_note ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/community-notes/introduction.mdx b/x-api/community-notes/introduction.mdx index 5b3fbd4e7..e1e9962e4 100644 --- a/x-api/community-notes/introduction.mdx +++ b/x-api/community-notes/introduction.mdx @@ -1,6 +1,7 @@ --- keywords: ["Community Notes", "community notes API", "AI Note Writer", "fact checking", "notes API", "community notes search", "notes evaluation"] ---- + +description: The Community Notes Endpoints in the X API v2 allow developers to search for and propose Community Notes on X programmatically. Use of the API requires ...--- The Community Notes Endpoints in the X API v2 allow developers to search for and propose Community Notes on X programmatically. Use of the API requires your account being signed up for X Developer AI access and enrolled in Community Notes as an AI Note Writer. You can [enroll and learn more about AI Note Writers](https://communitynotes.x.com/guide/en/api/overview) in the Community Notes Guide. diff --git a/x-api/community-notes/search-for-community-notes-written.mdx b/x-api/community-notes/search-for-community-notes-written.mdx index 3a8680ef8..31ad6dce4 100644 --- a/x-api/community-notes/search-for-community-notes-written.mdx +++ b/x-api/community-notes/search-for-community-notes-written.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/notes/search/notes_written ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/community-notes/search-for-posts-eligible-for-community-notes.mdx b/x-api/community-notes/search-for-posts-eligible-for-community-notes.mdx index d94faf9fa..07bd2628b 100644 --- a/x-api/community-notes/search-for-posts-eligible-for-community-notes.mdx +++ b/x-api/community-notes/search-for-posts-eligible-for-community-notes.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/notes/search/posts_eligible_for_notes ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/compliance/batch-compliance/integrate.mdx b/x-api/compliance/batch-compliance/integrate.mdx index ef1c1990e..bdee60666 100644 --- a/x-api/compliance/batch-compliance/integrate.mdx +++ b/x-api/compliance/batch-compliance/integrate.mdx @@ -1,222 +1,28 @@ ---- -title: Integration guide -sidebarTitle: Integration guide -keywords: ["batch compliance integration", "compliance batch integration", "compliance jobs integration", "batch compliance setup"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Working with resumable uploads - -When using the Batch compliance endpoints, developers can batch upload large amounts of X data and understand what action is needed to ensure that their datasets reflect user intent and the current state of the content on X. Uploading large amounts of data to a remote server is a relatively straightforward operation when systems and connectivity are stable and reliable. However, this may not always be the case. Some environments may impose a connection timeout, effectively cutting the connection between your app and the upload server after a set amount of time; you may also encounter connection issues, for example when trying to upload a large file from your laptop over a wi-fi connection. In these circumstances, it’s desirable to upload smaller portions of that file at a time, rather than having one single continuous connection. - -X's batch compliance endpoints rely on Google Cloud Storage to process large files. This type of storage is optimized for various applications; Cloud Storage supports a technique to manage large files called resumable uploads. - -If the upload goes wrong at any point, Google Cloud Storage is able to resume the operation from where it was left off. - -### Creating a resumable job - -#### Step one: - -First, you will have to create a compliance job and specify whether you will be uploading Post IDs or user IDs (using the type parameter). Additionally, add resumable to the body and set it to true. Make sure to replace the $APP\_ACCESS\_TOKEN below with your App only Access Token below. - -``` -curl --request POST \ - 'https://api.x.com/2/compliance/jobs' --header 'Authorization: Bearer $APP_ACCESS_TOKEN --header 'Content-Type: application/json' --data-raw '{ - "type": "tweets", - "resumable": true -}' -``` - -If your API call is successful, you will get a response similar to the following: - -``` -{ - "data": { - "download_expires_at": "2021-08-18T19:42:55.000Z", - "status": "created", - "upload_url": "https://storage.googleapis.com/twttr-tweet-compliance/1425543269983784962/submission/1202726487847104512_1425543269983784962?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=complianceapi-public-svc-acct%40twttr-compliance-public-prod.iam.gserviceaccount.com%2F20210811%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210811T194255Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=355e4c4739ae508304d3df15b4e13e64b6c7752d8d79d73676a4d8e60dc5241f83924ad2a1f8b7bddcc768062bb9c64d39b8e8f7cce7f66ffbea9f9ed33a4da975b3a2c127fb738c1c1ff3c3964bd4d9dc0706e6c8a70e67522160ea774e090d2793e06f890d1158ce86be3031c1c471b74f961b6f18743a28730611000336286ad0111b41fb5d14aa813ff00cf06b3572dc68d0b3c6fdc07f25c1b1196c1af4325a9ead68994944bbef0d2123585ea051deb9765aa7f5832446440bc9ba76af327b69df1fd7b1a99bd4419c128f1f697dbbacbc62bbc7c2c9aebc82a2128be0ed05d48a54d814162daad1232a0d13081e9543ab8557f567149af82281193f37", - "created_at": "2021-08-11T19:42:55.000Z", - "resumable": false, - "id": "1425543269983784962", - "type": "tweets", - "download_url": "https://storage.googleapis.com/twttr-tweet-compliance/1425543269983784962/delivery/1202726487847104512_1425543269983784962?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=complianceapi-public-svc-acct%40twttr-compliance-public-prod.iam.gserviceaccount.com%2F20210811%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210811T194255Z&X-Goog-Expires=604800&X-Goog-SignedHeaders=host&X-Goog-Signature=0a11dd5a3c5adb508f32ce904568abada863dc9499ba2adeafb3452ccee0dcb3dade17910dbc502dcbe54c130ac4d8638eb176c8b7344de068139b06c970794efa6312f0a5149f40da441eafcaf475f670c93ca73951999902a531d34dfab1e5490918929e5b06ae803b5604e0c0c26852255ccdbc79a2c1e2eefe924e5e6bf5b6603a7f287d1621333b9548ec6cc203716070528bebc2e67c12e92b1f4e54471db92c15a54799f2b855ae224250ca44c47993fd7d79a4940a0f68fe09f73fc8b291e88cfd10ade860b4b35c2b964d1777c1d93cd300c313138d9ca90aa8b3ecd3bf9dc73d3ebe32ba7634228fe07e1e4ecdda57cd94c802afc520162735d5a3", - "upload_expires_at": "2021-08-11T19:57:55.000Z" - } -} -``` - - -Take note of the value from the upload_url, you will need it in the following steps. - -#### Step two:  - -Next, you will need to initiate the resumable upload. In order to do so, make a **POST** call to the upload_url from the previous step and make sure to include the following headers: - -Content-Type: text/plain - -Content-Length: 0 - -x-goog-resumable: start - -``` -curl --request POST \ -'https://storage.googleapis.com/twttr-tweet-compliance/1430227686685757442/submission/1202726487847104512_1430227686685757442?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=complianceapi-public-svc-acct%40twttr-compliance-public-prod.iam.gserviceaccount.com%2F20210824%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210824T175707Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-length%3Bcontent-type%3Bhost%3Bx-goog-resumable&X-Goog-Signature=890d958f9c7dcb7f238e4971b59da5afc5b8329fb197c67b5930fe0f9dfe180afe2d4bec341111809b88ccfab46ab1f81f4242abc1af7b67c6e8977c52e6d486f5f43ce6a37a7a6530d25f15e2bcd9bb54655fe4ee22b26f8886ba71b67b7b11afd1198d658d1b6f0c41260f55260a260e1be0239977feba43dce40bc0e8e6293a4a3a3f7ee0afc74d3d2f7f2d3d514f108d5887a52ac85760385e5b9bb67cd26bfcf6b1c19151ea8111e217a29407722dc0dc9ab373334e88c18159546237ec9334f9a1e33717dc82800c6a45bba82706d5aece84ecdf3fcac52b21c8a3085a639047cf2707a8b9e4c296fc7cf05edbb110f07b89e38f0f5ea77e8b313cade7' \ ---header 'Content-Type: text/plain' --header \ - 'Content-Length: 0' --header \ - 'x-goog-resumable: start - ``` - - -If this call is successful, you will get a 201 response code. Then, in the response header, copy the value for the location header which will look something like this: - -``` -https://storage.googleapis.com/twttr-tweet-compliance/1430227686685757442/submission/1202726487847104512_1430227686685757442?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=complianceapi-public-svc-acct%40twttr-compliance-public-prod.iam.gserviceaccount.com%2F20210824%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20210824T175707Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-length%3Bcontent-type%3Bhost%3Bx-goog-resumable&X-Goog-Signature=890d958f9c7dcb7f238e4971b59da5afc5b8329fb197c67b5930fe0f9dfe180afe2d4bec341111809b88ccfab46ab1f81f4242abc1af7b67c6e8977c52e6d486f5f43ce6a37a7a6530d25f15e2bcd9bb54655fe4ee22b26f8886ba71b67b7b11afd1198d658d1b6f0c41260f55260a260e1be0239977feba43dce40bc0e8e6293a4a3a3f7ee0afc74d3d2f7f2d3d514f108d5887a52ac85760385e5b9bb67cd26bfcf6b1c19151ea8111e217a29407722dc0dc9ab373334e88c18159546237ec9334f9a1e33717dc82800c6a45bba82706d5aece84ecdf3fcac52b21c8a3085a639047cf2707a8b9e4c296fc7cf05edbb110f07b89e38f0f5ea77e8b313cade7&upload_id=ADPycds-_Ow7aqcpbG4XguXSVAgd_2fy-XiDA2qm-It9PCwBlZhF4e2bfOAQzEmRJ4T_l6jU6LfYdfrKa_KlFFBOyx3PjYzrxQ -``` - - -You can then upload your Post or User IDs to this location by following step two onwards, [from the quick start guide](/x-api/compliance/batch-compliance#getting-started-with-the-batch-compliance-endpoints). - - -Because of their technical complexity, resumable uploads are best used in conjunction with code. This guide will use Node.js with the [needle request library](https://www.npmjs.com/package/needle). - -### Install the dependencies - -Before proceeding, you should have a Node.js environment installed; you can obtain Node.js from its website. Once installed, Node.js will contain a utility called npm; make sure both Node and npm are installed by calling the following command, and ensure it doesn’t result in an error. - - `$ npm -v -6.4.1` - -A version number similar to this signifies your environment is ready (note that your version number may differ). We will use npm to install the upload library. Run this command: - - `$ npm install -g needle` - -You’re all set; there is no additional configuration required. - -#### Request a resumable destination - -When creating a new job, set the resumable parameter to true so you can get a destination that supports a resumable upload. In the response payload, you will receive an upload_url value. - -``` -"upload_url":\ -"https://storage.googleapis.com/compliance_tweet_ids/customer_test_object_12950882_GlYjiE?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=193969463581-compute%40developer.gserviceaccount.com%2F20200618%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200618T184154Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=b7bdcf32479b08715be91ed47b06471b8acdcdb319f8e4f423bf3a3056dfa03ed83e47446f33338e292967a15c08fa5ba34395edaf057a2ac975b88e710ca994adb023a9e1673a7c58ce2fa0d73537f72812af78e92b708dfe6b907a7d75bd0f6cfa61fec867e80ac83ced0725d1ee59787c9dbca50d41f7b0f513dad63a7564136b1a70042a2ec6ba6b697cbe480a4405362f7a08255a5e8205aa7baa562f99e6a092f0420f33d67ffaeb132f877fbaf16c969630b5f173e8a3f31c473707241fa4e28f4bed13fb2ea01d3af1c449321a2e6ee9ec1e331b447cabcfc6f9d1f99f564d180f0cc1d28ea54972c996102c67c6501c6c16a00c13d17756f960e0e1" -``` - -#### Prepare the code to upload a file - -By default, the library will create a new upload destination by accepting an upload location (called bucket) and the name of the file you wish to upload. Because the batch compliance endpoints create their own destination, we will need to tell the library we already have a location ready to accept our upload.  - - -We will need to pass this value to the upload library, along with the name of the file containing the data to upload. Create a file, and name it _**twitter-upload.js**_. Add the following code: - -``` -const needle = require('needle'); -const fs = require('fs'); -const path = require('path'); - -const [, scriptName, filename, uploadURL] = process.argv; -if (!filename || !uploadURL) { - console.error(`Usage: node ${path.basename(scriptName)} filename upload_url`); - process.exit(-1); -} - -async function uploadFile(file, url) { - // rangeEnd is the index of the last byte in the file, i.e. number of bytes in file - const rangeEnd = (await fs.promises.stat(file)).size; - - let options = { - headers: { - 'Content-Range': `bytes */${rangeEnd}`, - }, - }; - - const response = await needle('put', url, null, options); - - switch (response.statusCode) { - case 200: - case 201: - console.log('Upload complete'); - return; - case 308: - return resumeUpload(response, file, url); - default: - console.log('Got unexpected response code: ', response.statusCode); - return; - } -} - -async function resumeUpload(response, file, url) { - console.log('Upload not completed, resuming'); - if (response.headers.range) { - let resumeOffset = Number(response.headers.range.split('-')[1]) + 1; - - let options = { - headers: { - 'Content-Range': `bytes ${resumeOffset}-${rangeEnd-1}/${rangeEnd}`, - 'Content-Length': `${rangeEnd-resumeOffset}`, - }, - }; - - let readStream = fs.createReadStream(file, {start: resumeOffset}); - return needle('put', url, readStream, options); - } else { - console.log('Initiating upload'); - let options = { - headers: { - 'Content-Type': 'text/plain' - } - }; - - let readStream = fs.createReadStream(file); - return needle('put', url, readStream, options); - } -} - -// Request resumable session URL -async function requestResumableSession(url) { - const options = { - headers: { - 'Content-Type': 'text/plain', - 'Content-Length': '0', - 'x-goog-resumable': 'start', - }, - }; - - const res = await needle('post', url, null, options); - if (res.statusCode === 201) { - const resumableSessionURL = res.headers['location']; - console.log('Starting upload to: ', resumableSessionURL); - - await uploadFile(filename, resumableSessionURL); - } else { - console.log('Failed to create resumable session URI'); - } - -} - -requestResumableSession(uploadURL).then(result => console.log('Upload complete')); -``` - -Save the file wherever it makes the most sense. Next, in your command line, invoke the script and pass two parameters: - -1. The first will be the location of the file (with the Post or User IDs) that you wish to upload. -2. The second will be the upload URL we received from the compliance endpoint response. - -Ensure the URL is surrounded in double-quotes, and do the same for your file name if it contains spaces or other characters: - -``` -node twitter-upload.js compliance_upload.txt\ -"https://storage.googleapis.com/compliance_tweet_ids/customer_test_object_12950882_GlYjiE?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=193969463581-compute%40developer.gserviceaccount.com%2F20200618%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200618T184154Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=b7bdcf32479b08715be91ed47b06471b8acdcdb319f8e4f423bf3a3056dfa03ed83e47446f33338e292967a15c08fa5ba34395edaf057a2ac975b88e710ca994adb023a9e1673a7c58ce2fa0d73537f72812af78e92b708dfe6b907a7d75bd0f6cfa61fec867e80ac83ced0725d1ee59787c9dbca50d41f7b0f513dad63a7564136b1a70042a2ec6ba6b697cbe480a4405362f7a08255a5e8205aa7baa562f99e6a092f0420f33d67ffaeb132f877fbaf16c969630b5f173e8a3f31c473707241fa4e28f4bed13fb2ea01d3af1c449321a2e6ee9ec1e331b447cabcfc6f9d1f99f564d180f0cc1d28ea54972c996102c67c6501c6c16a00c13d17756f960e0e1" -``` - -You will see output similar to this: - - `Starting upload to: https://storage.googleapis.com/twttr-tweet-compliance/ -Upload not completed, resuming -Initiating upload` - -You can pause the upload at any time by pressing Ctrl + C or closing your command line. You will be able to resume the upload from where you left off when you invoke the same command at a later stage. Once the file has been completely uploaded, you will see the following message: - - `Upload complete` - -At this point, you will be able to use the [compliance status endpoint](/x-api/compliance/get-compliance-job) to check on the status of your compliance job, and you will be able to download the compliance result when complete. +--- +title: Integration guide +sidebarTitle: Integration guide +keywords: ["batch compliance integration", "compliance batch integration", "compliance jobs integration", "batch compliance setup"] + + +--- +import { Button } from '/snippets/button.mdx'; + +## Working with resumable uploads + +When using the Batch compliance endpoints, developers can batch upload large amounts of X data and understand what action is needed to ensure that their datasets reflect user intent and the current state of the content on X. Uploading large amounts of data to a remote server is a relatively straightforward operation when systems and connectivity are stable and reliable. However, this may not always be the case. Some environments may impose a connection timeout, effectively cutting the connection between your app and the upload server after a set amount of time; you may also encounter connection issues, for example when trying to upload a large file from your laptop over a wi-fi connection. In these circumstances, it’s desirable to upload smaller portions of that file at a time, rather than having one single continuous connection. + +X's batch compliance endpoints rely on Google Cloud Storage to process large files. This type of storage is optimized for various applications; Cloud Storage supports a technique to manage large files called resumable uploads. + +If the upload goes wrong at any point, Google Cloud Storage is able to resume the operation from where it was left off. + +### Creating a resumable job + +#### Step one: + +First, you will have to create a compliance job and specify whether you will be uploading Post IDs or user IDs (using the type parameter). Additionally, add resumable to the body and set it to true. Make sure to replace the $APP\_ACCESS\_TOKEN below with your App only Access Token below. + +``` +curl --request POST \ + 'https://api.x.com/2/compliance/jobs' --header 'Authorization: Bearer $APP_ACCESS_TOKEN --header 'Content-Type: application/json' --data-raw '{ + "type": "tweets", + \ No newline at end of file diff --git a/x-api/compliance/create-compliance-job.mdx b/x-api/compliance/create-compliance-job.mdx index 84dfc45d1..e72c0270d 100644 --- a/x-api/compliance/create-compliance-job.mdx +++ b/x-api/compliance/create-compliance-job.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/compliance/jobs ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/compliance/get-compliance-job-by-id.mdx b/x-api/compliance/get-compliance-job-by-id.mdx index 57cc5c311..932937eba 100644 --- a/x-api/compliance/get-compliance-job-by-id.mdx +++ b/x-api/compliance/get-compliance-job-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/compliance/jobs/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/compliance/get-compliance-jobs.mdx b/x-api/compliance/get-compliance-jobs.mdx index 95c296b56..ed9a9a62e 100644 --- a/x-api/compliance/get-compliance-jobs.mdx +++ b/x-api/compliance/get-compliance-jobs.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/compliance/jobs ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/compliance/streams/introduction.mdx b/x-api/compliance/streams/introduction.mdx index ba2ceacbb..dffc9e9cf 100644 --- a/x-api/compliance/streams/introduction.mdx +++ b/x-api/compliance/streams/introduction.mdx @@ -1,80 +1,80 @@ ---- -title: Introduction -sidebarTitle: Introduction -keywords: ["compliance streams", "compliance events", "compliance API", "compliance stream", "data compliance", "compliance monitoring"] ---- - -import { Button } from '/snippets/button.mdx'; - -X is committed to our community of developers who build with the X API. As part of this commitment, we aim to make our API open and fair to developers, safe for people on X and beneficial for the X platform as a whole. It is crucial that any developer who stores X content offline, ensures the data reflects user intent and the current state of content on X. For example, when someone on X deletes a Post or their account, protects their Posts, or edits a Post, it is critical for both X and our developers to honor that person's expectations and intent. - -Near real-time streams of compliance events provide developers the tools to maintain X data in compliance with the [X Developer Agreement and Policy](https://developer.x.com/en/developer-terms/policy). - -There are two compliance event streams, one for _Post compliance_ events, and one for _User compliance_ events. These streams are available with Enterprise access and are designed to help partners that ingest high volumes of data 'listen' for compliance events such as Post edit events. - -These streams provide the following events: - -**Post compliance stream:** - -* **delete** \- indicates that the Post was deleted. - -* **tweet_edi** \- indicates a Post has been edited and provides the ID of the updated Post. - -* **withheld** \- indicates that the Post has been withheld from one or more countries. - -* **drop** \- indicates that the Post should be removed from public view. - -* **undrop** \- indicates that the Post may be displayed again and treated as public. - - -**User compliance stream:** - -* **user_delete** \- indicates that the User account was deleted - -* **user_undelete** \- indicates that the User account was undeleted - -* **user_protect** \- indicates that the User account became private - -* **user_unprotect** \- indicates that the User account became public - -* **user_withheld** \- indicates that the User account has been withheld from one or more countries.  - -* **user_suspend** \- indicates that the User account was suspended -* **user_unsuspend** \- indicates that the User account was unsuspended -* **user\_profile\_modification** \- indicates that the User profile has been updated. This includes an updated description, name, location, and URL. - -**Account setup** - -To access these endpoints, you will need: - -* An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info). -* To authenticate using the keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  - -Learn more about getting access to the X API v2 endpoints in our [getting started guide](/x-api/getting-started/getting-access). -
- - -
- ---- - -## Streaming fundamentals - - - - Best practices for streaming clients - - - Reconnect gracefully - - - Handle high throughput - - - Build resilient applications - - +--- +title: Introduction +sidebarTitle: Introduction +keywords: ["compliance streams", "compliance events", "compliance API", "compliance stream", "data compliance", "compliance monitoring"] +--- + +import { Button } from '/snippets/button.mdx'; + +X is committed to our community of developers who build with the X API. As part of this commitment, we aim to make our API open and fair to developers, safe for people on X and beneficial for the X platform as a whole. It is crucial that any developer who stores X content offline, ensures the data reflects user intent and the current state of content on X. For example, when someone on X deletes a Post or their account, protects their Posts, or edits a Post, it is critical for both X and our developers to honor that person's expectations and intent. + +Near real-time streams of compliance events provide developers the tools to maintain X data in compliance with the [X Developer Agreement and Policy](https://developer.x.com/en/developer-terms/policy). + +There are two compliance event streams, one for _Post compliance_ events, and one for _User compliance_ events. These streams are available with Enterprise access and are designed to help partners that ingest high volumes of data 'listen' for compliance events such as Post edit events. + +These streams provide the following events: + +**Post compliance stream:** + +* **delete** \- indicates that the Post was deleted. + +* **tweet_edi** \- indicates a Post has been edited and provides the ID of the updated Post. + +* **withheld** \- indicates that the Post has been withheld from one or more countries. + +* **drop** \- indicates that the Post should be removed from public view. + +* **undrop** \- indicates that the Post may be displayed again and treated as public. + + +**User compliance stream:** + +* **user_delete** \- indicates that the User account was deleted + +* **user_undelete** \- indicates that the User account was undeleted + +* **user_protect** \- indicates that the User account became private + +* **user_unprotect** \- indicates that the User account became public + +* **user_withheld** \- indicates that the User account has been withheld from one or more countries.  + +* **user_suspend** \- indicates that the User account was suspended +* **user_unsuspend** \- indicates that the User account was unsuspended +* **user\_profile\_modification** \- indicates that the User profile has been updated. This includes an updated description, name, location, and URL. + +**Account setup** + +To access these endpoints, you will need: + +* An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info). +* To authenticate using the keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  + +Learn more about getting access to the X API v2 endpoints in our [getting started guide](/x-api/getting-started/getting-access). +
+ + +
+ +--- + +## Streaming fundamentals + + + + Best practices for streaming clients + + + Reconnect gracefully + + + Handle high throughput + + + Build resilient applications + + diff --git a/x-api/connections/get-connection-history.mdx b/x-api/connections/get-connection-history.mdx index fff3b9942..9f84e5246 100644 --- a/x-api/connections/get-connection-history.mdx +++ b/x-api/connections/get-connection-history.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/connections ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/connections/terminate-all-connections.mdx b/x-api/connections/terminate-all-connections.mdx index 6f4499329..eec4847be 100644 --- a/x-api/connections/terminate-all-connections.mdx +++ b/x-api/connections/terminate-all-connections.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/connections/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/connections/terminate-connections-by-endpoint.mdx b/x-api/connections/terminate-connections-by-endpoint.mdx index 3b36dadfc..1373898d3 100644 --- a/x-api/connections/terminate-connections-by-endpoint.mdx +++ b/x-api/connections/terminate-connections-by-endpoint.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/connections/{endpoint_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/connections/terminate-multiple-connections.mdx b/x-api/connections/terminate-multiple-connections.mdx index 5e2e0e1a2..fbc61eb40 100644 --- a/x-api/connections/terminate-multiple-connections.mdx +++ b/x-api/connections/terminate-multiple-connections.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/connections ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/blocks/introduction.mdx b/x-api/direct-messages/blocks/introduction.mdx index d682a957b..1f8f7e053 100644 --- a/x-api/direct-messages/blocks/introduction.mdx +++ b/x-api/direct-messages/blocks/introduction.mdx @@ -1,65 +1,66 @@ ---- -title: Introduction -sidebarTitle: Introduction -keywords: ["DM blocks", "direct message blocks", "block DMs", "DM blocking", "direct message blocking", "block messages"] ---- - -The manage DM blocks endpoints enable you to block or unblock a specified account on behalf of an authenticated user. For these endpoints, there are two POST methods available: - -* **/2/users/:id/dm/block**: Allows you to block an account -* **/2/users/:id/dm/unblock**: Allows you to unblock an account - - -### Getting started -### Authentication - -Since you are making requests on behalf of a user, you must authenticate these endpoints with either [OAuth 1.0a User Context](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) or [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2), and utilize the user Access Tokens associated with the user you are making the request on behalf of. You can generate this user Access Token using the [3-legged OAuth flow](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens) (OAuth 1.0a) or using the [Authorization Code with PKCE grant flow](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) (OAuth 2.0). - -### Making a request - -Block - -Once a user has authenticated with your app, you can call the Block endpoint on behalf of user as shown below: - - ``` - curl --request POST 'https://api.x.com/2/users/:id/dm/block' --header 'Authorization: ••••••' - ``` - - - - -If the request is successful, you should see the JSON response as shown below: - -``` -{ - "data": { - "blocked": true - } -} -``` - - - - -**Unblock** - -Once a user has authenticated with your app, you can call the Unblock endpoint on behalf of user as shown below: - - ``` - curl --request POST 'https://api.x.com/2/users/:id/dm/unblock' --header 'Authorization: ••••••' - ``` - - - - -If the request is successful, you should see the JSON response as shown below: - -``` -{ - "data": { - "blocked": false - } -} -``` - - +--- +title: Introduction +sidebarTitle: Introduction +keywords: ["DM blocks", "direct message blocks", "block DMs", "DM blocking", "direct message blocking", "block messages"] + +description: The manage DM blocks endpoints enable you to block or unblock a specified account on behalf of an authenticated user. For these endpoints, there are two...--- + +The manage DM blocks endpoints enable you to block or unblock a specified account on behalf of an authenticated user. For these endpoints, there are two POST methods available: + +* **/2/users/:id/dm/block**: Allows you to block an account +* **/2/users/:id/dm/unblock**: Allows you to unblock an account + + +### Getting started +### Authentication + +Since you are making requests on behalf of a user, you must authenticate these endpoints with either [OAuth 1.0a User Context](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) or [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2), and utilize the user Access Tokens associated with the user you are making the request on behalf of. You can generate this user Access Token using the [3-legged OAuth flow](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens) (OAuth 1.0a) or using the [Authorization Code with PKCE grant flow](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) (OAuth 2.0). + +### Making a request + +Block + +Once a user has authenticated with your app, you can call the Block endpoint on behalf of user as shown below: + + ``` + curl --request POST 'https://api.x.com/2/users/:id/dm/block' --header 'Authorization: ••••••' + ``` + + + + +If the request is successful, you should see the JSON response as shown below: + +``` +{ + "data": { + "blocked": true + } +} +``` + + + + +**Unblock** + +Once a user has authenticated with your app, you can call the Unblock endpoint on behalf of user as shown below: + + ``` + curl --request POST 'https://api.x.com/2/users/:id/dm/unblock' --header 'Authorization: ••••••' + ``` + + + + +If the request is successful, you should see the JSON response as shown below: + +``` +{ + "data": { + "blocked": false + } +} +``` + + diff --git a/x-api/direct-messages/create-dm-conversation.mdx b/x-api/direct-messages/create-dm-conversation.mdx index d6c7dbf87..b02c04808 100644 --- a/x-api/direct-messages/create-dm-conversation.mdx +++ b/x-api/direct-messages/create-dm-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/dm_conversations ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/create-dm-message-by-conversation-id.mdx b/x-api/direct-messages/create-dm-message-by-conversation-id.mdx index 956387ec1..7d3fbc1ec 100644 --- a/x-api/direct-messages/create-dm-message-by-conversation-id.mdx +++ b/x-api/direct-messages/create-dm-message-by-conversation-id.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/dm_conversations/{dm_conversation_id}/messages ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/create-dm-message-by-participant-id.mdx b/x-api/direct-messages/create-dm-message-by-participant-id.mdx index 4e9eb0f24..46318b3fe 100644 --- a/x-api/direct-messages/create-dm-message-by-participant-id.mdx +++ b/x-api/direct-messages/create-dm-message-by-participant-id.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/dm_conversations/with/{participant_id}/messages ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/delete-dm-event.mdx b/x-api/direct-messages/delete-dm-event.mdx index 14a42696f..a5bdbd851 100644 --- a/x-api/direct-messages/delete-dm-event.mdx +++ b/x-api/direct-messages/delete-dm-event.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/dm_events/{event_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/download-dm-media.mdx b/x-api/direct-messages/download-dm-media.mdx index 41739778e..074469121 100644 --- a/x-api/direct-messages/download-dm-media.mdx +++ b/x-api/direct-messages/download-dm-media.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_conversations/media/{dm_id}/{media_id}/{resource_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/get-dm-event-by-id.mdx b/x-api/direct-messages/get-dm-event-by-id.mdx index 03b648cf1..fd48fa1f2 100644 --- a/x-api/direct-messages/get-dm-event-by-id.mdx +++ b/x-api/direct-messages/get-dm-event-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_events/{event_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/get-dm-events-for-a-dm-conversation-1.mdx b/x-api/direct-messages/get-dm-events-for-a-dm-conversation-1.mdx index bcd2d6dd0..420a6b94f 100644 --- a/x-api/direct-messages/get-dm-events-for-a-dm-conversation-1.mdx +++ b/x-api/direct-messages/get-dm-events-for-a-dm-conversation-1.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_conversations/{id}/dm_events ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/get-dm-events-for-a-dm-conversation.mdx b/x-api/direct-messages/get-dm-events-for-a-dm-conversation.mdx index 37c967c67..d86382fe4 100644 --- a/x-api/direct-messages/get-dm-events-for-a-dm-conversation.mdx +++ b/x-api/direct-messages/get-dm-events-for-a-dm-conversation.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_conversations/with/{participant_id}/dm_events ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/get-dm-events.mdx b/x-api/direct-messages/get-dm-events.mdx index 89969dc9b..2b1eb0e0f 100644 --- a/x-api/direct-messages/get-dm-events.mdx +++ b/x-api/direct-messages/get-dm-events.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/dm_events ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/direct-messages/lookup/integrate.mdx b/x-api/direct-messages/lookup/integrate.mdx index 27a326dd5..377258c11 100644 --- a/x-api/direct-messages/lookup/integrate.mdx +++ b/x-api/direct-messages/lookup/integrate.mdx @@ -1,272 +1,271 @@ ---- -title: Integration Guide -sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating DM lookup endpoints -keywords: ["direct messages integration", "DM integration", "DM lookup integration"] ---- - -import { Button } from '/snippets/button.mdx'; - -This guide covers the key concepts you need to integrate the Direct Messages lookup endpoints into your application. - ---- - -## Authentication - -DM endpoints require user authentication to access private conversations: - -| Method | Description | -|:-------|:------------| -| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Recommended | -| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy support | - - -App-Only authentication is not supported. All Direct Messages are private. - - -### Required scopes (OAuth 2.0) - -| Scope | Required for | -|:------|:-------------| -| `dm.read` | Reading DM events | -| `tweet.read` | Required with dm.read | -| `users.read` | Required with dm.read | - ---- - -## Conversation types - - - - Always has exactly two participants. Conversation ID format: `{smaller_user_id}-{larger_user_id}` - - - Two or more participants. Membership can change over time. - - - ---- - -## Event types - -| Event | Description | Key fields | -|:------|:------------|:-----------| -| `MessageCreate` | A message was sent | `text`, `sender_id` | -| `ParticipantsJoin` | User joined group | `participant_ids`, `sender_id` | -| `ParticipantsLeave` | User left group | `participant_ids` | - -### Example events - - - -```json -{ - "id": "1582838499983564806", - "event_type": "MessageCreate", - "text": "Hi everyone.", - "sender_id": "944480690", - "dm_conversation_id": "1578398451921985538", - "created_at": "2022-10-19T20:58:00.000Z" -} -``` - - - -```json -{ - "id": "1582835469712138240", - "event_type": "ParticipantsJoin", - "participant_ids": ["944480690"], - "sender_id": "17200003", - "dm_conversation_id": "1578398451921985538", - "created_at": "2022-10-19T20:45:58.000Z" -} -``` - - - -```json -{ - "id": "1582838535115067392", - "event_type": "ParticipantsLeave", - "participant_ids": ["944480690"], - "dm_conversation_id": "1578398451921985538", - "created_at": "2022-10-19T20:58:09.000Z" -} -``` - - - ---- - -## Fields and expansions - -### Default fields - -| Event type | Default fields | -|:-----------|:---------------| -| MessageCreate | `id`, `event_type`, `text` | -| ParticipantsJoin/Leave | `id`, `event_type`, `participant_ids` | - -### Available fields - -| Field | Description | Events | -|:------|:------------|:-------| -| `dm_conversation_id` | Conversation ID | All | -| `created_at` | Event timestamp | All | -| `sender_id` | Who sent/invited | MessageCreate, Join | -| `attachments` | Media attachments | MessageCreate | -| `referenced_tweets` | Shared Posts | MessageCreate | - -### Available expansions - -| Expansion | Returns | -|:----------|:--------| -| `sender_id` | User object for sender | -| `participant_ids` | User objects for participants | -| `attachments.media_keys` | Media objects | -| `referenced_tweets.id` | Post objects | - -### Example with expansions - - - -```bash cURL -curl "https://api.x.com/2/dm_events?\ -dm_event.fields=created_at,sender_id,attachments&\ -expansions=sender_id,attachments.media_keys&\ -user.fields=username,profile_image_url&\ -media.fields=url,type" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Get DM events with expansions -for page in client.dm_events.list( - dm_event_fields=["created_at", "sender_id", "attachments"], - expansions=["sender_id", "attachments.media_keys"], - user_fields=["username", "profile_image_url"], - media_fields=["url", "type"], - max_results=100 -): - for event in page.data: - print(f"Event: {event.event_type} - {event.text}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -const paginator = client.dmEvents.list({ - dmEventFields: ["created_at", "sender_id", "attachments"], - expansions: ["sender_id", "attachments.media_keys"], - userFields: ["username", "profile_image_url"], - mediaFields: ["url", "type"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((event) => { - console.log(`Event: ${event.event_type} - ${event.text}`); - }); -} -``` - - - ---- - -## Pagination - -DM events are returned in reverse chronological order (newest first): - - - -```bash cURL -# First request -curl "https://api.x.com/2/dm_events?max_results=100" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" - -# Subsequent request with pagination token -curl "https://api.x.com/2/dm_events?max_results=100&pagination_token=NEXT_TOKEN" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# The SDK handles pagination automatically -all_events = [] - -for page in client.dm_events.list(max_results=100): - if page.data: - all_events.extend(page.data) - -print(f"Found {len(all_events)} DM events") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -async function getAllDMEvents() { - const allEvents = []; - - // The SDK handles pagination automatically - const paginator = client.dmEvents.list({ maxResults: 100 }); - - for await (const page of paginator) { - if (page.data) { - allEvents.push(...page.data); - } - } - - return allEvents; -} - -// Usage -const events = await getAllDMEvents(); -console.log(`Found ${events.length} DM events`); -``` - - - - -Events from up to **30 days ago** are available. - - ---- - -## ID compatibility with v1.1 - -Conversation and event IDs are shared between v1.1 and v2 endpoints. This means you can: - -- Use v2 to retrieve events, then use v1.1 to delete specific messages -- Reference conversation IDs from x.com URLs in API requests - ---- - -## Next steps - - - - Make your first DM lookup request - - - Send Direct Messages - - - Full endpoint documentation - - - Working code examples - - +--- +title: Integration Guide +sidebarTitle: Integration Guide +keywords: ["direct messages integration", "DM integration", "DM lookup integration"] +--- + +import { Button } from '/snippets/button.mdx'; + +This guide covers the key concepts you need to integrate the Direct Messages lookup endpoints into your application. + +--- + +## Authentication + +DM endpoints require user authentication to access private conversations: + +| Method | Description | +|:-------|:------------| +| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Recommended | +| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy support | + + +App-Only authentication is not supported. All Direct Messages are private. + + +### Required scopes (OAuth 2.0) + +| Scope | Required for | +|:------|:-------------| +| `dm.read` | Reading DM events | +| `tweet.read` | Required with dm.read | +| `users.read` | Required with dm.read | + +--- + +## Conversation types + + + + Always has exactly two participants. Conversation ID format: `{smaller_user_id}-{larger_user_id}` + + + Two or more participants. Membership can change over time. + + + +--- + +## Event types + +| Event | Description | Key fields | +|:------|:------------|:-----------| +| `MessageCreate` | A message was sent | `text`, `sender_id` | +| `ParticipantsJoin` | User joined group | `participant_ids`, `sender_id` | +| `ParticipantsLeave` | User left group | `participant_ids` | + +### Example events + + + +```json +{ + "id": "1582838499983564806", + "event_type": "MessageCreate", + "text": "Hi everyone.", + "sender_id": "944480690", + "dm_conversation_id": "1578398451921985538", + "created_at": "2022-10-19T20:58:00.000Z" +} +``` + + + +```json +{ + "id": "1582835469712138240", + "event_type": "ParticipantsJoin", + "participant_ids": ["944480690"], + "sender_id": "17200003", + "dm_conversation_id": "1578398451921985538", + "created_at": "2022-10-19T20:45:58.000Z" +} +``` + + + +```json +{ + "id": "1582838535115067392", + "event_type": "ParticipantsLeave", + "participant_ids": ["944480690"], + "dm_conversation_id": "1578398451921985538", + "created_at": "2022-10-19T20:58:09.000Z" +} +``` + + + +--- + +## Fields and expansions + +### Default fields + +| Event type | Default fields | +|:-----------|:---------------| +| MessageCreate | `id`, `event_type`, `text` | +| ParticipantsJoin/Leave | `id`, `event_type`, `participant_ids` | + +### Available fields + +| Field | Description | Events | +|:------|:------------|:-------| +| `dm_conversation_id` | Conversation ID | All | +| `created_at` | Event timestamp | All | +| `sender_id` | Who sent/invited | MessageCreate, Join | +| `attachments` | Media attachments | MessageCreate | +| `referenced_tweets` | Shared Posts | MessageCreate | + +### Available expansions + +| Expansion | Returns | +|:----------|:--------| +| `sender_id` | User object for sender | +| `participant_ids` | User objects for participants | +| `attachments.media_keys` | Media objects | +| `referenced_tweets.id` | Post objects | + +### Example with expansions + + + +```bash cURL +curl "https://api.x.com/2/dm_events?\ +dm_event.fields=created_at,sender_id,attachments&\ +expansions=sender_id,attachments.media_keys&\ +user.fields=username,profile_image_url&\ +media.fields=url,type" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") + +# Get DM events with expansions +for page in client.dm_events.list( + dm_event_fields=["created_at", "sender_id", "attachments"], + expansions=["sender_id", "attachments.media_keys"], + user_fields=["username", "profile_image_url"], + media_fields=["url", "type"], + max_results=100 +): + for event in page.data: + print(f"Event: {event.event_type} - {event.text}") +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); + +const paginator = client.dmEvents.list({ + dmEventFields: ["created_at", "sender_id", "attachments"], + expansions: ["sender_id", "attachments.media_keys"], + userFields: ["username", "profile_image_url"], + mediaFields: ["url", "type"], + maxResults: 100, +}); + +for await (const page of paginator) { + page.data?.forEach((event) => { + console.log(`Event: ${event.event_type} - ${event.text}`); + }); +} +``` + + + +--- + +## Pagination + +DM events are returned in reverse chronological order (newest first): + + + +```bash cURL +# First request +curl "https://api.x.com/2/dm_events?max_results=100" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" + +# Subsequent request with pagination token +curl "https://api.x.com/2/dm_events?max_results=100&pagination_token=NEXT_TOKEN" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") + +# The SDK handles pagination automatically +all_events = [] + +for page in client.dm_events.list(max_results=100): + if page.data: + all_events.extend(page.data) + +print(f"Found {len(all_events)} DM events") +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); + +async function getAllDMEvents() { + const allEvents = []; + + // The SDK handles pagination automatically + const paginator = client.dmEvents.list({ maxResults: 100 }); + + for await (const page of paginator) { + if (page.data) { + allEvents.push(...page.data); + } + } + + return allEvents; +} + +// Usage +const events = await getAllDMEvents(); +console.log(`Found ${events.length} DM events`); +``` + + + + +Events from up to **30 days ago** are available. + + +--- + +## ID compatibility with v1.1 + +Conversation and event IDs are shared between v1.1 and v2 endpoints. This means you can: + +- Use v2 to retrieve events, then use v1.1 to delete specific messages +- Reference conversation IDs from x.com URLs in API requests + +--- + +## Next steps + + + + Make your first DM lookup request + + + Send Direct Messages + + + Full endpoint documentation + + + Working code examples + + diff --git a/x-api/direct-messages/lookup/migrate.mdx b/x-api/direct-messages/lookup/migrate.mdx index 4f237a93a..1c895394a 100644 --- a/x-api/direct-messages/lookup/migrate.mdx +++ b/x-api/direct-messages/lookup/migrate.mdx @@ -1,85 +1,86 @@ ---- -title: Migration guide -sidebarTitle: Migration guide -keywords: ["direct messages migration", "DM migration", "v1.1 to v2 DM lookup", "DM migration guide", "migrate DM lookup"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing v1.1 and v2 Direct Message event lookup endpoints - - -Both v1.1 and v2 versions of the Direct Messages endpoints provide methods for looking up Direct Message events. This guide is intended to help understand the differences and provide information for migrating to v2.  - -A major difference between the two versions is that v1.1 supports only one-to-one conversations, while v2 introduces support for group conversations. One artifact of this is that v1.1 supports only "message created" events, while v2 also supports events associated with participants joining and leaving conversations. In fact, a fundamental v2 update is establishing dm_conversations as a core API object.    - -With v1.1. there are two endpoints for retrieving Direct Messages (again, new messages are the only event type supported with v1.1): - -* GET direct_messages/events/show \- Retrieves a single event by ID.  - -* GET direct_messages/events/list \- Retrieves up to 30 days of one-to-one Direct Messages sent and received by the authenticated user. Note that this method is not able to retrieve messages from group conversations.  - - -With this v2 release, there are three GET methods for retrieving Direct Message conversation events:  - -* **GET /2/dm\_conversations/with/:participant\_id/dm_events** \- Retrieves Direct Message events associated with a one-to-one conversation. The :participant_id path parameter is the User ID of the account having the conversation with the authenticated user making this request.  - -* **GET /2/dm\_conversations/:dm\_conversation\_id/dm\_events** \- Retrieves Direct Message events associated with a specific conversation ID, as indicated by the :dm\_conversation\_id path parameter. This method supports both one-to-one and group conversations.  - -* **GET /2/dm_events** \- Retrieves Direct Message events associated with a user, including both one-to-one and group conversations. Events from up to 30 days ago are available.   - - -An important detail is that conversation and event IDs are shared across v1.1 and v2 versions of the X Platform. This means both versions can be used together. For example, the Direct Messages v1.1 endpoints provide methods for returning a single event and for deleting events, methods not yet available with v2. Since IDs are common across v1.1 and v2, you can make v1.1 requests based on IDs provided by v2, or by referencing conversation IDs displayed in conversation URLs on the X application. - -The following table compares fundamental aspects of the v1.1 and v2 Direct Message event lookup endpoints. The X API v2 characteristics shared here are common to all of the Direct Message lookup endpoints. - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint root path | [/1.1/direct_messages](https://api.x.com/1.1/direct_messages) | [/2/dm_conversations](https://api.x.com/2/users/:id/dm_conversations)

Direct Messages conversations are introduced as a fundamental API object. 

These endpoints retrieve MessageCreate, ParticipantsJoin, and ParticipantLeave events. | -| HTTP methods supported | GET | GET | -| Supports Group Direct Messages | | ✔ | -| Event types supported | message_create | MessageCreate, ParticipantsJoin, ParticipantsLeave | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2 User Context (scopes: dm.read, tweet.read, user.read) | -| Requires the use of credentials from a [developer App](/resources/fundamentals/authentication) associated with a X API v2 [Project](/resources/fundamentals/developer-apps) | | ✔ | -| Default request [rate limits](/x-api/fundamentals/rate-limits)*
*All requests require user tokens | | GET requests: 300 requests per 15 mins

Rate limit is applied across all three endpoints | - -The following tables compare the v2 GET methods with version v1.1. Note that these v2 offerings expand the available capabilities by supporting group conversations.  - -**Get all messages in a specific one-to-one conversation ** - --------------------------------------------------------------- - -Path: GET /2/dm\_conversations/with/:participant\_id/dm_events - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| Endpoint path | GET 

/1.1/direct_messages/events/list | GET /2/dm\_conversations/with/:participant\_id/dm_events | -| How much event history is available | 30 days | No limit | -| Default request [rate limits](/x-api/fundamentals/rate-limits) | 15 requests per 15 minutes | 300 requests per 15 minutes
Rate limit is applied across all three GET endpoints | - -**Get all messages by conversation ID ** - -Path: GET /2/dm\_conversations/:dm\_conversation\_id/dm\_events - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| Endpoint path | Not supported. V1.1 can return messages from one-to-one conversations only and there is no support for retrieving events by conversation IDs. | GET /2/dm\_conversations/:dm\_conversation\_id/dm\_events | -| How much event history is available | 30 days | No limit | -| Supports group conversations | | ✔ | -| Default request [rate limits](/x-api/fundamentals/rate-limits) | 15 requests per 15 minutes | 300 requests per 15 minutes
Rate limit is applied across all three GET endpoints | - -**Get all events across an authenticated user's conversations, both one-to-one and group conversations** - -Path: GET /2/dm_events - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| Endpoint path | GET /1.1/direct_messages/events/list

V1.1 can return messages from one-to-one conversations only. | GET /2/dm_events | -| How much event history is available | 30 days | 30 days | -| Supports group conversations | | ✔ | -| Default request [rate limits](/x-api/fundamentals/rate-limits) | 15 requests per 15 minutes | 300 requests per 15 minutes
Rate limit is applied across all three GET endpoints | +--- +title: Migration guide +sidebarTitle: Migration guide +keywords: ["direct messages migration", "DM migration", "v1.1 to v2 DM lookup", "DM migration guide", "migrate DM lookup"] + +description: 1 and v2 versions of the Direct Messages endpoints provide methods for looking up Direct Message events.--- + +import { Button } from '/snippets/button.mdx'; + +## Comparing v1.1 and v2 Direct Message event lookup endpoints + + +Both v1.1 and v2 versions of the Direct Messages endpoints provide methods for looking up Direct Message events. This guide is intended to help understand the differences and provide information for migrating to v2.  + +A major difference between the two versions is that v1.1 supports only one-to-one conversations, while v2 introduces support for group conversations. One artifact of this is that v1.1 supports only "message created" events, while v2 also supports events associated with participants joining and leaving conversations. In fact, a fundamental v2 update is establishing dm_conversations as a core API object.    + +With v1.1. there are two endpoints for retrieving Direct Messages (again, new messages are the only event type supported with v1.1): + +* GET direct_messages/events/show \- Retrieves a single event by ID.  + +* GET direct_messages/events/list \- Retrieves up to 30 days of one-to-one Direct Messages sent and received by the authenticated user. Note that this method is not able to retrieve messages from group conversations.  + + +With this v2 release, there are three GET methods for retrieving Direct Message conversation events:  + +* **GET /2/dm\_conversations/with/:participant\_id/dm_events** \- Retrieves Direct Message events associated with a one-to-one conversation. The :participant_id path parameter is the User ID of the account having the conversation with the authenticated user making this request.  + +* **GET /2/dm\_conversations/:dm\_conversation\_id/dm\_events** \- Retrieves Direct Message events associated with a specific conversation ID, as indicated by the :dm\_conversation\_id path parameter. This method supports both one-to-one and group conversations.  + +* **GET /2/dm_events** \- Retrieves Direct Message events associated with a user, including both one-to-one and group conversations. Events from up to 30 days ago are available.   + + +An important detail is that conversation and event IDs are shared across v1.1 and v2 versions of the X Platform. This means both versions can be used together. For example, the Direct Messages v1.1 endpoints provide methods for returning a single event and for deleting events, methods not yet available with v2. Since IDs are common across v1.1 and v2, you can make v1.1 requests based on IDs provided by v2, or by referencing conversation IDs displayed in conversation URLs on the X application. + +The following table compares fundamental aspects of the v1.1 and v2 Direct Message event lookup endpoints. The X API v2 characteristics shared here are common to all of the Direct Message lookup endpoints. + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint root path | [/1.1/direct_messages](https://api.x.com/1.1/direct_messages) | [/2/dm_conversations](https://api.x.com/2/users/:id/dm_conversations)

Direct Messages conversations are introduced as a fundamental API object. 

These endpoints retrieve MessageCreate, ParticipantsJoin, and ParticipantLeave events. | +| HTTP methods supported | GET | GET | +| Supports Group Direct Messages | | ✔ | +| Event types supported | message_create | MessageCreate, ParticipantsJoin, ParticipantsLeave | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2 User Context (scopes: dm.read, tweet.read, user.read) | +| Requires the use of credentials from a [developer App](/resources/fundamentals/authentication) associated with a X API v2 [Project](/resources/fundamentals/developer-apps) | | ✔ | +| Default request [rate limits](/x-api/fundamentals/rate-limits)*
*All requests require user tokens | | GET requests: 300 requests per 15 mins

Rate limit is applied across all three endpoints | + +The following tables compare the v2 GET methods with version v1.1. Note that these v2 offerings expand the available capabilities by supporting group conversations.  + +**Get all messages in a specific one-to-one conversation ** + +-------------------------------------------------------------- + +Path: GET /2/dm\_conversations/with/:participant\_id/dm_events + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| Endpoint path | GET 

/1.1/direct_messages/events/list | GET /2/dm\_conversations/with/:participant\_id/dm_events | +| How much event history is available | 30 days | No limit | +| Default request [rate limits](/x-api/fundamentals/rate-limits) | 15 requests per 15 minutes | 300 requests per 15 minutes
Rate limit is applied across all three GET endpoints | + +**Get all messages by conversation ID ** + +Path: GET /2/dm\_conversations/:dm\_conversation\_id/dm\_events + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| Endpoint path | Not supported. V1.1 can return messages from one-to-one conversations only and there is no support for retrieving events by conversation IDs. | GET /2/dm\_conversations/:dm\_conversation\_id/dm\_events | +| How much event history is available | 30 days | No limit | +| Supports group conversations | | ✔ | +| Default request [rate limits](/x-api/fundamentals/rate-limits) | 15 requests per 15 minutes | 300 requests per 15 minutes
Rate limit is applied across all three GET endpoints | + +**Get all events across an authenticated user's conversations, both one-to-one and group conversations** + +Path: GET /2/dm_events + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| Endpoint path | GET /1.1/direct_messages/events/list

V1.1 can return messages from one-to-one conversations only. | GET /2/dm_events | +| How much event history is available | 30 days | 30 days | +| Supports group conversations | | ✔ | +| Default request [rate limits](/x-api/fundamentals/rate-limits) | 15 requests per 15 minutes | 300 requests per 15 minutes
Rate limit is applied across all three GET endpoints | diff --git a/x-api/direct-messages/manage/integrate.mdx b/x-api/direct-messages/manage/integrate.mdx index 6301776fd..cac4e9761 100644 --- a/x-api/direct-messages/manage/integrate.mdx +++ b/x-api/direct-messages/manage/integrate.mdx @@ -1,290 +1,289 @@ ---- -title: Integration Guide -sidebarTitle: Integration Guide -description: Key concepts and best practices for sending Direct Messages -keywords: ["manage direct messages integration", "DM management integration", "send DM integration"] ---- - -import { Button } from '/snippets/button.mdx'; - -This guide covers the key concepts you need to integrate the manage Direct Messages endpoints into your application. - ---- - -## Authentication - -DM endpoints require user authentication: - -| Method | Description | -|:-------|:------------| -| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Recommended | -| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy support | - - -App-Only authentication is not supported. All Direct Messages are private. - - -### Required scopes (OAuth 2.0) - -| Scope | Required for | -|:------|:-------------| -| `dm.write` | Sending and deleting messages | -| `dm.read` | Required with dm.write | -| `tweet.read` | Required with dm scopes | -| `users.read` | Required with dm scopes | - ---- - -## Endpoints overview - -| Method | Endpoint | Description | -|:-------|:---------|:------------| -| POST | `/2/dm_conversations/with/:participant_id/messages` | Send one-to-one message | -| POST | `/2/dm_conversations` | Create group conversation | -| POST | `/2/dm_conversations/:dm_conversation_id/messages` | Add message to conversation | -| DELETE | `/2/dm_events/:event_id` | Delete a message | - ---- - -## Sending messages - -### One-to-one message - -Send a message to a specific user. Creates a new conversation if one doesn't exist: - - - -```bash cURL -curl -X POST "https://api.x.com/2/dm_conversations/with/9876543210/messages" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"text": "Hello!"}' -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Send a one-to-one DM -response = client.dm_conversations.create_message( - participant_id="9876543210", - text="Hello!" -) -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -// Send a one-to-one DM -const response = await client.dmConversations.createMessage({ - participantId: "9876543210", - text: "Hello!", -}); -console.log(response.data); -``` - - - -### Group conversation - -Create a new group and send the first message: - - - -```bash cURL -curl -X POST "https://api.x.com/2/dm_conversations" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "conversation_type": "Group", - "participant_ids": ["944480690", "906948460078698496"], - "message": {"text": "Welcome to our group!"} - }' -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Create a group conversation -response = client.dm_conversations.create( - conversation_type="Group", - participant_ids=["944480690", "906948460078698496"], - message={"text": "Welcome to our group!"} -) -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -// Create a group conversation -const response = await client.dmConversations.create({ - conversationType: "Group", - participantIds: ["944480690", "906948460078698496"], - message: { text: "Welcome to our group!" }, -}); -console.log(response.data); -``` - - - - -The `conversation_type` field must be set to `"Group"` (case sensitive). - - -### Add to existing conversation - -Send a message to any conversation you're part of: - - - -```bash cURL -curl -X POST "https://api.x.com/2/dm_conversations/1582103724607971328/messages" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"text": "Another message"}' -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Add message to existing conversation -response = client.dm_conversations.add_message( - dm_conversation_id="1582103724607971328", - text="Another message" -) -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -// Add message to existing conversation -const response = await client.dmConversations.addMessage({ - dmConversationId: "1582103724607971328", - text: "Another message", -}); -console.log(response.data); -``` - - - ---- - -## Media attachments - -Attach one piece of media (photo, video, or GIF) per message. - - - - Use the [Media Upload endpoint](/x-api/media/quickstart/media-upload-chunked) to upload your file and get a `media_id`. - - - -```json -{ - "text": "Check out this image!", - "attachments": [{"media_id": "1583157113245011970"}] -} -``` - - - - -- The authenticated user must have uploaded the media -- Media is available for 24 hours after upload -- Only one attachment per message is supported - - ---- - -## Sharing Posts - -Include a Post in your message by adding the Post URL to the text: - -```json -{ - "text": "Have you seen this? https://x.com/XDevelopers/status/1580559079470145536" -} -``` - -The response will include a `referenced_tweets` field with the Post ID. - ---- - -## Message requirements - -| Field | Required | Notes | -|:------|:---------|:------| -| `text` | Yes* | Required if no attachments | -| `attachments` | Yes* | Required if no text | - -*At least one of `text` or `attachments` must be provided. - ---- - -## ID compatibility with v1.1 - -Conversation and event IDs are shared between v1.1 and v2 endpoints. This enables hybrid workflows: - -- Create messages with v2 -- Delete messages with v1.1 (not yet available in v2) -- Reference conversation IDs from x.com URLs - ---- - -## Error handling - -| Status | Error | Solution | -|:-------|:------|:---------| -| 400 | Invalid request | Check request body format | -| 401 | Unauthorized | Verify access token | -| 403 | Forbidden | Check scopes and user permissions | -| 429 | Too Many Requests | Wait and retry | - -### Common issues - - - - The recipient may have DM settings that prevent messages from unknown users, or may have blocked you. - - - - Ensure the media was uploaded by the same authenticated user and is less than 24 hours old. - - - - Verify all participant IDs are valid and the users allow group DM invites. - - - ---- - -## Next steps - - - - Send your first Direct Message - - - Retrieve DM conversations - - - Upload media for attachments - - - Full endpoint documentation - - +--- +title: Integration Guide +sidebarTitle: Integration Guide +keywords: ["manage direct messages integration", "DM management integration", "send DM integration"] +--- + +import { Button } from '/snippets/button.mdx'; + +This guide covers the key concepts you need to integrate the manage Direct Messages endpoints into your application. + +--- + +## Authentication + +DM endpoints require user authentication: + +| Method | Description | +|:-------|:------------| +| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Recommended | +| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy support | + + +App-Only authentication is not supported. All Direct Messages are private. + + +### Required scopes (OAuth 2.0) + +| Scope | Required for | +|:------|:-------------| +| `dm.write` | Sending and deleting messages | +| `dm.read` | Required with dm.write | +| `tweet.read` | Required with dm scopes | +| `users.read` | Required with dm scopes | + +--- + +## Endpoints overview + +| Method | Endpoint | Description | +|:-------|:---------|:------------| +| POST | `/2/dm_conversations/with/:participant_id/messages` | Send one-to-one message | +| POST | `/2/dm_conversations` | Create group conversation | +| POST | `/2/dm_conversations/:dm_conversation_id/messages` | Add message to conversation | +| DELETE | `/2/dm_events/:event_id` | Delete a message | + +--- + +## Sending messages + +### One-to-one message + +Send a message to a specific user. Creates a new conversation if one doesn't exist: + + + +```bash cURL +curl -X POST "https://api.x.com/2/dm_conversations/with/9876543210/messages" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"text": "Hello!"}' +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") + +# Send a one-to-one DM +response = client.dm_conversations.create_message( + participant_id="9876543210", + text="Hello!" +) +print(response.data) +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); + +// Send a one-to-one DM +const response = await client.dmConversations.createMessage({ + participantId: "9876543210", + text: "Hello!", +}); +console.log(response.data); +``` + + + +### Group conversation + +Create a new group and send the first message: + + + +```bash cURL +curl -X POST "https://api.x.com/2/dm_conversations" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "conversation_type": "Group", + "participant_ids": ["944480690", "906948460078698496"], + "message": {"text": "Welcome to our group!"} + }' +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") + +# Create a group conversation +response = client.dm_conversations.create( + conversation_type="Group", + participant_ids=["944480690", "906948460078698496"], + message={"text": "Welcome to our group!"} +) +print(response.data) +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); + +// Create a group conversation +const response = await client.dmConversations.create({ + conversationType: "Group", + participantIds: ["944480690", "906948460078698496"], + message: { text: "Welcome to our group!" }, +}); +console.log(response.data); +``` + + + + +The `conversation_type` field must be set to `"Group"` (case sensitive). + + +### Add to existing conversation + +Send a message to any conversation you're part of: + + + +```bash cURL +curl -X POST "https://api.x.com/2/dm_conversations/1582103724607971328/messages" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"text": "Another message"}' +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") + +# Add message to existing conversation +response = client.dm_conversations.add_message( + dm_conversation_id="1582103724607971328", + text="Another message" +) +print(response.data) +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); + +// Add message to existing conversation +const response = await client.dmConversations.addMessage({ + dmConversationId: "1582103724607971328", + text: "Another message", +}); +console.log(response.data); +``` + + + +--- + +## Media attachments + +Attach one piece of media (photo, video, or GIF) per message. + + + + Use the [Media Upload endpoint](/x-api/media/quickstart/media-upload-chunked) to upload your file and get a `media_id`. + + + +```json +{ + "text": "Check out this image!", + "attachments": [{"media_id": "1583157113245011970"}] +} +``` + + + + +- The authenticated user must have uploaded the media +- Media is available for 24 hours after upload +- Only one attachment per message is supported + + +--- + +## Sharing Posts + +Include a Post in your message by adding the Post URL to the text: + +```json +{ + "text": "Have you seen this? https://x.com/XDevelopers/status/1580559079470145536" +} +``` + +The response will include a `referenced_tweets` field with the Post ID. + +--- + +## Message requirements + +| Field | Required | Notes | +|:------|:---------|:------| +| `text` | Yes* | Required if no attachments | +| `attachments` | Yes* | Required if no text | + +*At least one of `text` or `attachments` must be provided. + +--- + +## ID compatibility with v1.1 + +Conversation and event IDs are shared between v1.1 and v2 endpoints. This enables hybrid workflows: + +- Create messages with v2 +- Delete messages with v1.1 (not yet available in v2) +- Reference conversation IDs from x.com URLs + +--- + +## Error handling + +| Status | Error | Solution | +|:-------|:------|:---------| +| 400 | Invalid request | Check request body format | +| 401 | Unauthorized | Verify access token | +| 403 | Forbidden | Check scopes and user permissions | +| 429 | Too Many Requests | Wait and retry | + +### Common issues + + + + The recipient may have DM settings that prevent messages from unknown users, or may have blocked you. + + + + Ensure the media was uploaded by the same authenticated user and is less than 24 hours old. + + + + Verify all participant IDs are valid and the users allow group DM invites. + + + +--- + +## Next steps + + + + Send your first Direct Message + + + Retrieve DM conversations + + + Upload media for attachments + + + Full endpoint documentation + + diff --git a/x-api/direct-messages/manage/migrate.mdx b/x-api/direct-messages/manage/migrate.mdx index 9a88886fa..28851ea49 100644 --- a/x-api/direct-messages/manage/migrate.mdx +++ b/x-api/direct-messages/manage/migrate.mdx @@ -1,81 +1,82 @@ ---- -title: Migration guide -sidebarTitle: Migration guide -keywords: ["manage direct messages migration", "DM management migration", "v1.1 to v2 manage DMs", "DM migration guide", "migrate DM management"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing v1.1 and v2 Manage Direct Message endpoints - -Both v1.1 and v2 versions of the Direct Messages endpoints provide methods for creating Direct Message messages. This guide is intended to help understand the differences and provide information for migrating to v2.  - -A major difference between the two versions is that v1.1 supports only one-to-one conversations, while v2 introduces support for group conversations. One artifact of this is that v1.1 supports only "message created" events, while v2 also supports events associated with participants joining and leaving conversations. In fact, a fundamental v2 update is establishing dm_conversations as a core API object.    - -With v1.1. there are two endpoints for managing Direct Messages: - -* POST direct_messages/events/new \- Creates a one-to-one Direct Message. This v1.1 endpoint can only create one-to-one messages, and does not support group messages.   - -* DELETE direct_messages/events/destroy \- Deletes a one-to-one message from the view of the authenticating user.  - - -With this v2 release, there are three POST methods for creating Direct Messages:  - -* **POST /2/dm\_conversations/with/:participant\_id/messages** \- Creates a one-to-one Direct Message. This method either adds the message to an existing one-to-one conversation or creates a new one. The :participant_id path parameter is the User ID of the account receiving the message.  - -* **POST /2/dm_conversations** \- Creates a new group conversation and adds a Direct Message to it. These requests require a list of conversation participants. Note that you can create multiple conversations with the same participant list. These requests will always return a new conversation ID.  - -* **POST /2/dm\_conversations/:dm\_conversation_id/messages** \- Creates a Direct Message and adds it to an existing conversation. The :dm\_conversation\_id path parameter is the ID of the conversation that the message will be added to.  - - -An important detail is that conversation and event IDs are shared across v1.1 and v2 versions of the X Platform. This means both versions can be used together. For example, the Direct Messages v1.1 endpoints provide methods for returning a single event and for deleting events, methods not yet available with v2. Since IDs are common across v1.1 and v2, you can make v1.1 requests based on IDs provided by v2, or by referencing conversation IDs displayed in conversation URLs on the X application. - -The following table compares fundamental aspects of the v1.1 and v2 manage Direct Messages endpoints. The X API v2 characteristics shared here are common to all of the Direct Message lookup endpoints. - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint root path | [/1.1/direct_messages](https://api.x.com/1.1/direct_messages) | [/2/dm_conversations](https://api.x.com/2/users/:id/dm_conversations)

Direct Messages conversations are introduced as a fundamental API object. 

These endpoints retrieve MessageCreate, ParticipantsJoin, and ParticipantLeave events. | -| HTTP methods supported | POST | POST | -| Supports Group Direct Messages | | ✔ | -| Event types supported | message_create | MessageCreate, ParticipantsJoin, ParticipantsLeave | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2 User Context (scopes: dm.read, dm.write) | -| Requires the use of credentials from a [developer App](/resources/fundamentals/authentication) associated with a X API v2 [Project](/resources/fundamentals/developer-apps) | | ✔ | -| Default request [rate limits](/x-api/fundamentals/rate-limits)*
*All requests require user tokens | 1000 requests per user per 24 hours
15000 requests per app per 24 hours | 200 requests per 15 minutes per user

1000 requests per user per 24 hours

15000 requests per app per 24 hours

These rate limits are shared across all dm_conversations POST endpoints. | - -The following tables compare the v2 POST methods with version v1.1. Note that these v2 offerings expand the available capabilities by supporting group conversations.  - -**Create a new one-to-one Direct Message** - -Path: POST /2/dm\_conversations/with/:participant\_id/messages - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| Endpoint path | POST direct\_messages/events/new (message\_create) | POST /2/dm\_conversations/with/:participant\_id/messages | -| Default request [rate limits](/x-api/fundamentals/rate-limits) | 1000 requests per user per 24 hours
15000 requests per app per 24 hours | 200 requests per 15 minutes per user

1000 requests per user per 24 hours

15000 requests per app per 24 hours

These rate limits are shared across all dm_conversations POST endpoints. | -| Supports group Direct Messages | | ✔ | - -**Create a new Direct Message group conversation and add a message to it** - -Path: POST /2/dm_conversations - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| Endpoint path | Not supported | POST /2/dm_conversations | -| Default request [rate limits](/x-api/fundamentals/rate-limits) | | 200 requests per 15 minutes per user

1000 requests per user per 24 hours

15000 requests per app per 24 hours

These rate limits are shared across all dm_conversations POST endpoints. | -| Supports group Direct Messages | | ✔ | - -**Add a Direct Message to an existing conversation by ID** - -Path: POST /2/dm\_conversations/:dm\_conversation_id/messages - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| Endpoint path | Not supported | POST /2/dm\_conversations/:dm\_conversation_id/messages | -| Default request [rate limits](/x-api/fundamentals/rate-limits) | | 200 requests per 15 minutes per user

1000 requests per user per 24 hours

15000 requests per app per 24 hours

These rate limits are shared across all dm_conversations POST endpoints. | -| Supports group Direct Messages | | ✔ | - +--- +title: Migration guide +sidebarTitle: Migration guide +keywords: ["manage direct messages migration", "DM management migration", "v1.1 to v2 manage DMs", "DM migration guide", "migrate DM management"] + +description: 1 and v2 versions of the Direct Messages endpoints provide methods for creating Direct Message messages.--- + +import { Button } from '/snippets/button.mdx'; + +## Comparing v1.1 and v2 Manage Direct Message endpoints + +Both v1.1 and v2 versions of the Direct Messages endpoints provide methods for creating Direct Message messages. This guide is intended to help understand the differences and provide information for migrating to v2.  + +A major difference between the two versions is that v1.1 supports only one-to-one conversations, while v2 introduces support for group conversations. One artifact of this is that v1.1 supports only "message created" events, while v2 also supports events associated with participants joining and leaving conversations. In fact, a fundamental v2 update is establishing dm_conversations as a core API object.    + +With v1.1. there are two endpoints for managing Direct Messages: + +* POST direct_messages/events/new \- Creates a one-to-one Direct Message. This v1.1 endpoint can only create one-to-one messages, and does not support group messages.   + +* DELETE direct_messages/events/destroy \- Deletes a one-to-one message from the view of the authenticating user.  + + +With this v2 release, there are three POST methods for creating Direct Messages:  + +* **POST /2/dm\_conversations/with/:participant\_id/messages** \- Creates a one-to-one Direct Message. This method either adds the message to an existing one-to-one conversation or creates a new one. The :participant_id path parameter is the User ID of the account receiving the message.  + +* **POST /2/dm_conversations** \- Creates a new group conversation and adds a Direct Message to it. These requests require a list of conversation participants. Note that you can create multiple conversations with the same participant list. These requests will always return a new conversation ID.  + +* **POST /2/dm\_conversations/:dm\_conversation_id/messages** \- Creates a Direct Message and adds it to an existing conversation. The :dm\_conversation\_id path parameter is the ID of the conversation that the message will be added to.  + + +An important detail is that conversation and event IDs are shared across v1.1 and v2 versions of the X Platform. This means both versions can be used together. For example, the Direct Messages v1.1 endpoints provide methods for returning a single event and for deleting events, methods not yet available with v2. Since IDs are common across v1.1 and v2, you can make v1.1 requests based on IDs provided by v2, or by referencing conversation IDs displayed in conversation URLs on the X application. + +The following table compares fundamental aspects of the v1.1 and v2 manage Direct Messages endpoints. The X API v2 characteristics shared here are common to all of the Direct Message lookup endpoints. + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint root path | [/1.1/direct_messages](https://api.x.com/1.1/direct_messages) | [/2/dm_conversations](https://api.x.com/2/users/:id/dm_conversations)

Direct Messages conversations are introduced as a fundamental API object. 

These endpoints retrieve MessageCreate, ParticipantsJoin, and ParticipantLeave events. | +| HTTP methods supported | POST | POST | +| Supports Group Direct Messages | | ✔ | +| Event types supported | message_create | MessageCreate, ParticipantsJoin, ParticipantsLeave | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2 User Context (scopes: dm.read, dm.write) | +| Requires the use of credentials from a [developer App](/resources/fundamentals/authentication) associated with a X API v2 [Project](/resources/fundamentals/developer-apps) | | ✔ | +| Default request [rate limits](/x-api/fundamentals/rate-limits)*
*All requests require user tokens | 1000 requests per user per 24 hours
15000 requests per app per 24 hours | 200 requests per 15 minutes per user

1000 requests per user per 24 hours

15000 requests per app per 24 hours

These rate limits are shared across all dm_conversations POST endpoints. | + +The following tables compare the v2 POST methods with version v1.1. Note that these v2 offerings expand the available capabilities by supporting group conversations.  + +**Create a new one-to-one Direct Message** + +Path: POST /2/dm\_conversations/with/:participant\_id/messages + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| Endpoint path | POST direct\_messages/events/new (message\_create) | POST /2/dm\_conversations/with/:participant\_id/messages | +| Default request [rate limits](/x-api/fundamentals/rate-limits) | 1000 requests per user per 24 hours
15000 requests per app per 24 hours | 200 requests per 15 minutes per user

1000 requests per user per 24 hours

15000 requests per app per 24 hours

These rate limits are shared across all dm_conversations POST endpoints. | +| Supports group Direct Messages | | ✔ | + +**Create a new Direct Message group conversation and add a message to it** + +Path: POST /2/dm_conversations + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| Endpoint path | Not supported | POST /2/dm_conversations | +| Default request [rate limits](/x-api/fundamentals/rate-limits) | | 200 requests per 15 minutes per user

1000 requests per user per 24 hours

15000 requests per app per 24 hours

These rate limits are shared across all dm_conversations POST endpoints. | +| Supports group Direct Messages | | ✔ | + +**Add a Direct Message to an existing conversation by ID** + +Path: POST /2/dm\_conversations/:dm\_conversation_id/messages + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| Endpoint path | Not supported | POST /2/dm\_conversations/:dm\_conversation_id/messages | +| Default request [rate limits](/x-api/fundamentals/rate-limits) | | 200 requests per 15 minutes per user

1000 requests per user per 24 hours

15000 requests per app per 24 hours

These rate limits are shared across all dm_conversations POST endpoints. | +| Supports group Direct Messages | | ✔ | + diff --git a/x-api/enterprise-gnip-2.0/enterprise-gnip.mdx b/x-api/enterprise-gnip-2.0/enterprise-gnip.mdx index 7a1f2aedd..5c8de7b93 100644 --- a/x-api/enterprise-gnip-2.0/enterprise-gnip.mdx +++ b/x-api/enterprise-gnip-2.0/enterprise-gnip.mdx @@ -1,7 +1,8 @@ --- title: Enterprise keywords: ["enterprise API", "GNIP", "enterprise data", "enterprise access", "enterprise API", "GNIP API", "enterprise"] ---- + +description: Our enterprise APIs offer the highest level of access and reliability to those who depend on X data. Perfect as you scale beyond premium and need more r...--- import { Button } from '/snippets/button.mdx'; diff --git a/x-api/enterprise-gnip-2.0/fundamentals/account-activity.mdx b/x-api/enterprise-gnip-2.0/fundamentals/account-activity.mdx index 44b37975c..80d0fc09c 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/account-activity.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/account-activity.mdx @@ -1,7 +1,8 @@ --- title: "Account Activity API: Enterprise" keywords: ["enterprise Account Activity API", "enterprise AAA", "Account Activity enterprise", "enterprise webhooks", "enterprise activity"] ---- + +description: Overview `Enterprise` The Account Activity API provides you the ability to subscribe to realtime activities related to a user account via webhooks. This...--- This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the ["Edit Posts" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets).  @@ -170,1945 +171,4 @@ Great job! You should now able to manage your webhooks and subscribed users. In this video walkthrough, you will learn about the capabilities of the premium and enterprise tiers of the Account Activity API. -By the end of this video, you will learn about the following capabilities. - -* Registering a webhook -* Adding a user subscription -* Removing a user subscription -* Receiving account activities -* Replay account activities - - - - -* Have questions? Running into errors? - * Read our [Frequently asked questions](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#frequently-asked-questions) or [Error Troubleshooting guide](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#frequently-asked-questions). - - -* Explore our sample code: - * [Enterprise Account Activity API dashboard](https://github.com/xdevplatform/account-activity-dashboard-enterprise), a node web app that displays webhook events using the enterprise tier of the Account Activity API and includes [Replay](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-replay-api) functionality. - * The [SnowBot chatbot](https://github.com/xdevplatform/SnowBotDev), a Ruby web app built on the enterprise Account Activity and Direct Message APIs. - -**Enterprise** - -## Getting started with webhooks - -The Account Activity API is a webhook-based API that sends account events to a web app you develop, deploy and host.  - -There are several 'plumbing' details that need attention before you can start receiving webhook events in your event consumer application. As described below, you will need to create a X app, obtain Account Activity API access, and develop a web app that consumes webhook events.  - -### 1\. Create a X app. - -* Create a [X app](/resources/fundamentals/developer-apps) with an approved developer account from the [Developer Console](/resources/fundamentals/developer-portal). If you are creating the app on behalf of your company, it is recommended you create the app with a corporate X account. To apply for a developer account, [click here](/resources/fundamentals/developer-apps). -* Enable “Read, Write and Access direct messages” on the [permissions](/resources/fundamentals/developer-apps#oauth-1-0a-app-permissions) tab of your app page. -* On the "Keys and Access Tokens" tab, take note of your app's Consumer Key (API Key) and Consumer Token (API Secret). -* On the same tab, generate your app's [Access Token and Access Token Secret](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). You will need these Access Tokens to register your webhook URL, which is where X will send account events. -* If you are unfamiliar with [X Sign-in](/resources/fundamentals/authentication#log-in-with-x) and how user contexts work with the X API review [Obtaining Access Tokens](https://dev.x.com/webhooks/access-tokens). As you add accounts for which to receive events, you will subscribe them using that account's access tokens. -* Take note of your app's numeric ID, as seen in the ["Apps"](/resources/fundamentals/developer-apps) page of the [Developer Console](/resources/fundamentals/developer-portal). When you apply for Account Activity API access, you'll need this app ID. -   - -### 2\. Get Account Activity API access - -After creating a X app, the next step is applying for Account Activity API access.  - -Account Activity API is only availble on Enterprise, so you will need to submit an application using the link below. - - -### 3\. Develop webhook consumer app - -Once you have received Account Activity API access, you need to develop, deploy and host a web app that will receive X webhook events.  - -* Create a web app with a URL to use as your webhook to receive events. This is the endpoint deployed on your server to listen for incoming X webhook events.  - * The URI _path_ is completely up to you. This example would be valid: https://mydomain.com_/service/listen_ - - * If you are listening for webhooks from a variety of sources, a common pattern is: https://mydomain.com/webhook/twitter - * Note that the specified URL can not include a port specification (https://mydomain.com:5000/NoWorkie). -* As described in our [Securing Webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#securing-webhooks) guide, a first step is writing code that receives a X Challenge Response Check (CRC) GET request and responds with a properly formatted JSON response.  -* Register your webhook URL. You will make a POST request to a /webhooks.json?url= endpoint. When you make this request X will issue a CRC request to your web app. When a webhook is successfully registered, the response will include a webhook id. This webhook id is needed later when making some requests to the Account Activity API.  - -* X will send account webhook events to the URL you registered. Make sure your web app supports POST requests for incoming events. These events will be encoded in JSON. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-data-object-structure) for example webhook JSON payloads. -* Once your web app is ready, the next step is adding accounts to receive activities for. When adding (or deleting) accounts you will make POST requests referencing the account id. See our [guide on adding subscriptions](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#managing-webhooks-and-subscriptions) for more information. - - - -### 4\. Validate setup - -* To validate your app and webhook are configured correctly, favorite a Post posted by one of the X accounts your app is subscribed to. You should receive a `favorite_events` via a POST request to your webhook URL for each Favorite your subscribers receive. -* Note that it may take up to 10 seconds for events to start being delivered after a subscription has been added. - -**Important Notes** - -* When registering your webhook URL, your web app must authenticate with its consumer token and secret _and the app owner's user access token and secret_.  -* All incoming Direct Messages will be delivered via webhooks. All Direct Messages sent via [POST direct\_messages/events/new (message\_create)](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) will also be delivered via webhooks. This is so your web app can be aware of Direct Messages sent via a different client. -* Note that every webhook event includes a for\_user\_id user ID that indicates which subscription the event was delivered for. -* If you have two users using your web app for Direct Messages in the same conversation, your webhook will receive two duplicate events (one for each user). Your web app should account for this.  - -* If you have more than one web app sharing the same webhook URL and the same user mapped to each app, the same event will be sent to your webhook multiple times (once per web app). -* In some cases, your webhook may receive duplicate events. Your webhook app should be tolerant of this and dedupe by event ID. -* Do not expect Quick Reply response to directly follow a request. A user has the ability to ignore a Quick Reply request and may respond via traditional Direct Message. The user may also provide a Quick Reply response to a request they have not replied to earlier in the message thread. - - - -* See example code: - * [Enterprise Account Activity API dashboard](https://github.com/xdevplatform/account-activity-dashboard-enterprise), a node web app that displays webhook events using the enterprise tier of the Account Activity API and includes [Replay](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-replay-api) functionality. - - * The [SnowBot chatbot](https://github.com/xdevplatform/SnowBotDev), a Ruby web app built on the Account Activity and Direct Message APIs. This code base includes a [script](https://github.com/xdevplatform/SnowBotDev/wiki/Account-Activity-API-setup-script) to help set up Account Activity API webhooks. - - -## Securing webhooks - -X's webhook-based APIs provide two methods for confirming the security of your webhook server: - -1. The challenge-response checks enable X to confirm the ownership of the web app receiving webhook events.  -2. The signature header in each POST request enables you to confirm that X is the source of the incoming webhooks. -   - - -### Challenge-Response Checks  - -In order to verify that you are both the owner of the app and the webhook URL, X will perform a Challenge-Response Check (CRC), which is not to be confused with a cyclic redundancy check. When a CRC is sent, X will make a GET request of your web app with a ;_`crc_token`_ parameter. When that request is received, your web app needs to build an encrypted `response_token` based on the _`crc_token`_ parameter and your app's Consumer Secret (details below). The response_token must be encoded in JSON (see example below) and returned within three seconds. When successful, a webhook `id` will be returned.  - -A CRC will be sent when you register your webhook URL, so implementing your CRC response code is a fundamental first step. Once your webhook is established, X will trigger a CRC roughly every 24 hours from the last time we received a successful response. Your app can also trigger a CRC when needed by making a PUT request with your webhook `id`. Triggering a CRC is useful as you develop your webhook application, after deploying new code and restarting your service.  - -The _`crc_token`_ should be expected to change for each incoming CRC request and should be used as the message in the calculation, where your Consumer Secret is the key. - -In the event that the response is not posted within 3 seconds or becomes invalid, events will cease to be sent to the registered webhook. - -#### The CRC request will occur: - -* When a webhook URL is registered. -* Approximately _hourly_ to validate your webhook URL. -* You can manually trigger a CRC by making a PUT request. As you develop your webhook client, you should plan on manually triggering the CRC as you develop your CRC response.  -   - -#### Response requirements: - -* A base64 encoded HMAC SHA-256 hash created from the `crc_token` and your app Consumer Secret -* Valid response_token and JSON format. -* Latency less than 3 seconds. -* 200 HTTP response code. -   - -#### Language-specific HMAC libraries: - -* [Java/Scala](https://docs.oracle.com/javase/8/docs/api/index.html?javax/crypto/Mac.html) -* [Ruby](http://ruby-doc.org/stdlib-2.1.0/libdoc/openssl/rdoc/OpenSSL/HMAC.html) -* [Node.js](https://nodejs.org/api/crypto.html#crypto_class_hmac) -* [Python](https://docs.python.org/2/library/hmac.html) - -#### Example response token generation in Python: - -The following defines a route in a Python 2.7 Flask webapp that will respond to the challenge response check correctly. -``` -import base64 -import hashlib -import hmac -import json - - -\# Defines a route for the GET request -@app.route('/webhooks/twitter', methods=\['GET'\]) -def webhook_challenge(): - -  # creates HMAC SHA-256 hash from incomming token and your consumer secret -  sha256\_hash\_digest = hmac.new(TWITTER\_CONSUMER\_SECRET, msg=request.args.get('crc_token'), digestmod=hashlib.sha256).digest() - -  # construct response data with base64 encoded hash -  response = { -    'response\_token': 'sha256=' + base64.b64encode(sha256\_hash_digest) -  } - -  # returns properly formatted json response -  return json.dumps(response) -``` - -#### Example JSON response: - -With the route defined as above your webapp should return a response similar to below when navigating to https://your-app-domain/webhooks/twitter?crc_token=foo in your web browser. -``` -{ - "response_token": "sha256=x0mYd8hz2goCTfcNAaMqENy2BFgJJfJOb4PdvTffpwg=" -} -``` -#### Other examples: - -* [HERE](https://github.com/xdevplatform/account-activity-dashboard/blob/master/helpers/security.js) is an example CRC response method written in Node/JS. -* [HERE](https://github.com/xdevplatform/SnowBotDev/blob/master/app/controllers/snow_bot_dev_app.rb) is an example CRC response method written in Ruby (see the _generate\_crc\_response_ and the /GET route that receives CRC events). - - - -### Optional signature header validation - -When receiving a POST request from X, sending a GET request to create a webhook, or sending a GET request to perform a manual CRC, a hash signature will be passed in the headers as x-twitter-webhooks-signature. This signature can be used to validate the source of the data is X. The POST hash signature starts with sha256= indicating the use of HMAC SHA-256 to encrypt your X App Consumer Secret and payload. The GET hash is calculated from the query parameter string crc_token=$token&nonce=$nonce.  - -**Steps to validate a request** - -1. Create a hash using your consumer secret and incoming payload body. -2. Compare created hash with the base64 encoded x-twitter-webhooks-signature value. Use a method like [compare_digest](https://docs.python.org/2/library/hmac.html) to reduce the vulnerability to timing attacks. - - - -### Additional security guidelines - -The following are additional security guidelines to consider for your web application. Not having these guidelines implemented will not prevent your webhook from functioning, but are highly reccomended by the X Information Security team. If you are unfamilair with the below recommendations consult with your server administrator. - -#### X aggregate network blocks - -For added security you may wish to add the following aggregate network blocks to an allowlist: - -* 199.59.148.0/22 -* 199.16.156.0/22 -* 192.133.77.0/26 -* 64.63.15.0/24 - -* 64.63.31.0/24 -* 64.63.47.0/24 -* 202.160.128.0/24 -* 202.160.129.0/24 -* 202.160.130.0/24 - -#### Recommended server configurations - -* "A" rating on [ssllabs.com](http://ssllabs.com/) test -* **Enable TLS 1.2** -* Enable Forward Secrecy -* Turn off SSLv2 -* Turn off SSLv3 (because of POODLE) -* Turn off TLS 1.0 -* Turn off TLS 1.1 -* Turn off TLS Compression -* Turn off Session Tickets unless you rotate session ticket keys. -* Set the “ssl\_prefer\_server_ciphers” or “SSLHonorCipherOrder” option in the SSL Configuration “on”. -* Ensure the list of ciphers is a modern list such as: - `ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:DES-CBC3-SHA` - - -## Managing webhooks and subscriptions - -### Creating & changing webhooks - -In order to change webhook URLs, you must delete your existing webhook and then create a new one. Note that when you do this, you will be required to re-add user subscriptions to the new webhook. - -#### Webhook configuration management endpoints: - - -| | | -| :--- | :--- | -| **Method** | Enterprise | -| Registers a webhook URL / Generates a webhook_id | [POST webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) | -| Returns all webhook URLs and their statuses | [GET webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) | -| Delete app’s current webhook configuration | [DELETE webhooks/:webhook_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id) | -| Manually trigger a CRC request | [PUT webhooks/:webhook_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id) | - -#### Why can’t I just update the webhook URL? - -Why are webhook configurations immutable? X takes security very seriously. If your webhook URL is changed, there is a possibility that your application consumer key and consumer secret have been compromised. By requiring you to create a new webhook configuration, you are also required to re-subscribe to your user’s events. This requires the use of access tokens that a malicious party is less likely to possess. As a result, the likelihood that another party will receive your user’s private information is reduced. -  - -### Adding & removing User subscriptions - -Support for thousands of subscriptions is available with the enterprise tier. If you already have an account manager, please reach out to them with questions.  To apply for access to the enterprise APIs, [click here](https://developer.x.com/en/products/x-api/enterprise).  - -#### Subscription management endpoints -  - -| | | -| :--- | :--- | -| Method | Enterprise | -| Add new user subscription | [POST webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all) | -| Retrieve a user subscription | [GET webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all) | -| Returns a list of all active subscriptions | [GET webhooks/:webhook_id/subscriptions/all/list](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | -| Deactivates a user subscription using application only OAuth | [DELETE webhooks/:webhook\_id/subscriptions/:user\_id/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json) | - - - -Account Activity API: Enterprise - -**Please note**:  - -X needs to enable access to the Account Activity API for your developer App before you can start using the API. To this end, make sure to share the App ID that you intend to use for authentication purposes with your account manager or technical support team. - - -The [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) consists of a set of endpoints that allow you to create and manage user subscriptions to receive real-time account activities for all of your subscribed accounts through a single connection.  - -There are two authentication methods available with the Account Activity API ([OAuth 1.0a](/resources/fundamentals/authentication#oauth-1-0a-2) and [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). The authentication method that you should use will depend on which endpoint you are using. - -| | | | | -| :--- | :--- | :--- | :--- | -| **Description** | **Endpoint ** | OAuth 1.0a
(user context) | OAuth 2.0 Bearer Token (application-only) | -| Register a new webhook URL for the given application context | [POST account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks) | ✓ | | -| Return all URLs and their statuses for the given application | [GET account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) | | ✓ | -| Trigger a challenge response check (CRC) for a given webhook's URL | [PUT account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id) | ✓ | | -| Subscribe the application to a user’s account events | [POST account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all) | ✓ * | | -| Return a count of currently active subscriptions | [GET account_activity/subscriptions/count](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | | ✓ | -| Check if a webhook configuration is subscribed to a user’s events | [GET account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all) | ✓ * | | -| Return a list of currently active subscriptions | [GET account\_activity/webhooks/:webhook\_id/subscriptions/all/list](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all-list) | | ✓ | -| Delete a webhook | [DELETE account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id) | ✓ | | -| \[DEPRECATED\] Deactivate a subscription for the provided user context and application | [DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) | ✓ * | | -| Deactivate a subscription using application-only OAuth | [DELETE /account\_activity/webhooks/:webhook\_id/subscriptions/:user_id/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json) | | ✓ | -| Redelivers activities to a webhook | [POST /1.1/account\_activity/replay/webhooks/:webhook\_id/subscriptions/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#replay-api) | | ✓ | - -*_ Authentication requires the access tokens of the subscribing user. _ - -For those endpoints that require OAuth 1.0a user context authentication, you will need to provide the following credentials to authenticate the request:  - -* Consumer Keys (API Key and Secret) -* Access Tokens (Access Token and Secret) - -In the case of the following three endpoints, you perform write actions within the context of your application (no X users are involved). Therefore, the Access Tokens you need to provide are the ones belonging to your developer App. These can be generated directly from within the [Developer Console](https://developer.x.com/en/portal/projects-and-apps), under the “Keys and tokens” tab for your App.   - -* [POST account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks): Register a new webhook URL for the given application context -* [PUT account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id): Trigger a challenge response check (CRC) for a given webhook's URL -* [DELETE account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id): Delete a webhook - -On the other hand, in the case of the following three endpoints, you are making a request that allows your application to access protected data on behalf of a X user (for example, Direct Messages). You must therefore provide the Access Tokens that belong to the subscribing user in question. The required Access tokens can be obtained using the 3-legged OAuth flow (see [OAuth 1.0a: how to obtain a user’s Access Tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow)). These endpoints have been marked with an asterisk in the above table (*). - -* [POST account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all): Subscribe the application to a user’s account events -* [GET account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all): Check if a webhook configuration is subscribed to a user’s events -* [DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated): Deactivate a subscription for the provided user context and application \[DEPRECATED\] - - -**Please note**:  - -Make sure that your developer App is enabled for "Read, Write, and Direct Messages." You can change this setting in the [Projects & Apps section](https://developer.x.com/en/portal/projects-and-apps) of your developer account, under “App permissions” for the selected developer App. You will need to regenerate your App credentials after changing the permissions settings. - -A list of all endpoints available with the Account Activity API, including associated description and example cURL requests with authentication implementation examples, can be found in[the API reference documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-api-reference-index). - -For additional information, check out XDev’s [sample web app and helper scripts](https://github.com/xdevplatform/account-activity-dashboard-enterprise) to get started with the Enterprise Account Activity API. - - -**Please note**:  - -X needs to enable access to the Account Activity API for your developer App before you can start using the API. To this end, make sure to share the App ID that you intend to use for authentication purposes with your account manager or technical support team. - -The [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) consists of a set of endpoints that allow you to create and manage user subscriptions to receive real-time account activities for all of your subscribed accounts through a single connection.  - -There are two authentication methods available with the Account Activity API ([OAuth 1.0a](/resources/fundamentals/authentication#oauth-1-0a-2) and [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#oauth-2-0)). The authentication method that you should use will depend on which endpoint you are using. - -| | | | | -| :--- | :--- | :--- | :--- | -| **Description** | **Endpoint ** | OAuth 1.0a
(user context) | OAuth 2.0 Bearer Token (application-only) | -| Register a new webhook URL for the given application context | [POST account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks) | ✓ | | -| Return all URLs and their statuses for the given application | [GET account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) | | ✓ | -| Trigger a challenge response check (CRC) for a given webhook's URL | [PUT account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id) | ✓ | | -| Subscribe the application to a user’s account events | [POST account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all) | ✓ * | | -| Return a count of currently active subscriptions | [GET account_activity/subscriptions/count](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | | ✓ | -| Check if a webhook configuration is subscribed to a user’s events | [GET account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all) | ✓ * | | -| Return a list of currently active subscriptions | [GET account\_activity/webhooks/:webhook\_id/subscriptions/all/list](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all-list) | | ✓ | -| Delete a webhook | [DELETE account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id) | ✓ | | -| \[DEPRECATED\] Deactivate a subscription for the provided user context and application | [DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) | ✓ * | | -| Deactivate a subscription using application-only OAuth | [DELETE /account\_activity/webhooks/:webhook\_id/subscriptions/:user_id/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json) | | ✓ | -| Redelivers activities to a webhook | [POST /1.1/account\_activity/replay/webhooks/:webhook\_id/subscriptions/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#replay-api) | | ✓ | - -*_ Authentication requires the access tokens of the subscribing user. _ - -For those endpoints that require OAuth 1.0a user context authentication, you will need to provide the following credentials to authenticate the request:  - -* Consumer Keys (API Key and Secret) -* Access Tokens (Access Token and Secret) - -In the case of the following three endpoints, you perform write actions within the context of your application (no X users are involved). Therefore, the Access Tokens you need to provide are the ones belonging to your developer App. These can be generated directly from within the [Developer Console](https://developer.x.com/en/portal/projects-and-apps), under the “Keys and tokens” tab for your App.   - -* [POST account_activity/webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks): Register a new webhook URL for the given application context -* [PUT account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id): Trigger a challenge response check (CRC) for a given webhook's URL -* [DELETE account\_activity/webhooks/:webhook\_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id): Delete a webhook - -On the other hand, in the case of the following three endpoints, you are making a request that allows your application to access protected data on behalf of a X user (for example, Direct Messages). You must therefore provide the Access Tokens that belong to the subscribing user in question. The required Access tokens can be obtained using the 3-legged OAuth flow (see [OAuth 1.0a: how to obtain a user’s Access Tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow)). These endpoints have been marked with an asterisk in the above table (*). - -* [POST account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all): Subscribe the application to a user’s account events -* [GET account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all): Check if a webhook configuration is subscribed to a user’s events -* [DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated): Deactivate a subscription for the provided user context and application \[DEPRECATED\] - - -**Please note**:  - -Make sure that your developer App is enabled for "Read, Write, and Direct Messages." You can change this setting in the [Projects & Apps section](https://developer.x.com/en/portal/projects-and-apps) of your developer account, under “App permissions” for the selected developer App. You will need to regenerate your App credentials after changing the permissions settings. - -A list of all endpoints available with the Account Activity API, including associated description and example cURL requests with authentication implementation examples, can be found in[the API reference documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-api-reference-index). - -For additional information, check out XDev’s [sample web app and helper scripts](https://github.com/xdevplatform/account-activity-dashboard-enterprise) to get started with the Enterprise Account Activity API. - - -## Retries - -`Enterprise` - -One of the benefits of the enterprise tier of the Account Activity API is a retry mechanism for webhook events. If a 'success' 200 HTTP response code is not received, the X server will initiate a retry mechanism, resending the webhook event up to three times over a five-minute period. This webhook event retry service helps provide reliability and event recovery when network problems occur and during client-side service interruptions and deploys. -  - -### What are retries? - -The Account Activity API provides a retry feature when the client's web app does not return a 'success' 200 response for an account activity webhook event. When the client-side does not confirm the successful receipt of an event, X assumes the event was not received. If a non-200 response is received, a response isn't received within three seconds, or we don't receive a response at all, we retry the request and leave that open for three seconds. This means that you have roughly five seconds over two attempts to respond to receive the activity that we are trying to send to your webhook URL. In the event that your server doesn't response or returns a transient error, we will retry for five minutes. There will be a total of three retry attempts to confirm validation. This allows redundancy and insurance that you receive all webhook events. Note that subscriptions with retries will get retried events for any/all activities for all subscribed users on their webhook. - -If you do not confirm validation within these eight attempts, the activity will no longer be available via the Account Activity API.  - - -### Retry timeline - -The Account Activity API will retry up to three times over a five-minute period until a 200 response is received.  Refer to the table below for more details. After around five minutes, the activity cannot be resent through the Account Activity API. You will need to use other X endpoints to collect missed data. For example, the [search APIs](/x-api/enterprise-gnip-2.0/fundamentals/search-api) can be used to retrieve relevant Posts, Retweets, Quote Tweets, Mentions, and Replies. Missed Direct Messages can be retrieved with [this endpoint](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events). - -#### Retries timeline - -| | -| :--- | -| Activity created, POST to the webhook URL from Account Activity API and times out in three seconds. | -| Wait three seconds after previous timeout finishes, then POST to the webhook URL from Account Activity API and times out in three seconds. | -| Wait 27 seconds after previous timeout finishes, then POST to the webhook URL from Account Activity API and times out in three seconds. | -| Wait 242 seconds after previous timeout finishes, then POST to the webhook URL from Account Activity API and times out in three seconds | -| The Account Activity API will stop attempting to POST after this. Client must use other X endpoints to recover data. | - - -## Account Activity data object structure - -| Object | Details | -| :--- | :--- | -| for\_user\_id | Identifies the user subscription subscribed that the event is related to. | -| is\_blocked\_by | (conditional) Shown only when another user mentions your subscribed user. Included if true for Post mention events only. | -| source | The user that is performing the activity. For example, the user that is following, blocking, or muting is the source user. | -| target | The user that the activity applies to. For example, the user that is being followed, blocked, or muted is the target user. | - - -**Available Activities** - -| Message Type | Details | -| :--- | :--- | -| [tweet\_create\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#tweet-create-events-posts-retweets-replies-quotetweets) | Post status payload when any of the following actions are taken by or to the subscription user: Posts, Retweets, Replies, @mentions, QuoteTweets, Retweet of Quote Tweets. | -| [favorite_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#favorite-events) | Favorite (like) event status with the user and target. | -| [follow_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#follow-events) | Follow event with the user and target. | -| [unfollow_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#unfollow-events) | Unfollow event with the user and target. | -| [block_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#block-events) | Block event with the user and target. | -| [unblock_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#unblock-events) | Unblock event with the user and target. | -| [mute_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#mute-events) | Mute event with the user and target. | -| [unmute_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#unmute-events) | Unmute event with the user and target. | -| [user_event](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#user-event) | Revoke events sent when a user removes application authorization and subscription is automatically deleted. | -| [direct\_message\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-events) | Direct message status with the user and target when a direct message is sent or received. | -| [direct\_message\_indicate\_typing\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-indicate-typing-events) | Direct message typing event with the user and target. | -| [direct\_message\_mark\_read\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-mark-read-events) | Direct message read event with the user and target. | -| [tweet\_delete\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#tweet-delete-events) | Notice of deleted Posts to make it easier to maintain compliance. | - -**Payload examples** - -See the payload examples below for each Account Activity event described in the table above. - -#### tweet\_create\_events (Posts, Retweets, Replies, QuoteTweets)  - -``` -{ - "for_user_id": "2244994945", - "tweet_create_events": [ - { - - } - ] -} -``` - - -#### tweet\_create\_events (@mentions)  - -``` -{ - "for_user_id": "2244994945", - "user_has_blocked": "false", - "tweet_create_events": [ - { - - } - ] -} -``` - -#### favorite_events - -``` -{ - "for_user_id": "2244994945", - "favorite_events": [{ - "id": "a7ba59eab0bfcba386f7acedac279542", - "created_at": "Mon Mar 26 16:33:26 +0000 2018", - "timestamp_ms": 1522082006140, - "favorited_status": { - - }, - "user": { - - } - }] -} -``` - -#### follow_events - -``` -{ - "for_user_id": "2244994945", - "follow_events": [{ - "type": "follow", - "created_timestamp": "1517588749178", - "target": { - - }, - "source": { - < User Object > - } - ] - } -} -``` - -#### unfollow_events - -``` -{ - "for_user_id": "2244994945", - "follow_events": [{ - "type": "unfollow", - "created_timestamp": "1517588749178", - "target": { - - }, - "source": { - < User Object > - } - ] - } -} -``` - -#### block_events - -``` -{ - "for_user_id": "2244994945", - "block_events": [{ - "type": "block", - "created_timestamp": "1518127020304", - "source": { - - }, - "target": { - - } - }] -} -``` - -#### unblock_events -``` -{ - "for_user_id": "2244994945", - "block_events": [{ - "type": "unblock", - "created_timestamp": "1518127020304", - "source": { - - }, - "target": { - - } - }] -} -``` - -#### mute_events - -``` -{ - "for_user_id": "2244994945", - "mute_events": [ - { - "type": "mute", - "created_timestamp": "1518127020304", - "source": { - - }, - "target": { - - } - } - ] -} -``` - -#### unmute_events - -``` -{ - "for_user_id": "2244994945", - "mute_events": [ - { - "type": "unmute", - "created_timestamp": "1518127020304", - "source": { - - }, - "target": { - - } - } - ] -} -``` - -#### user_event - -``` -{ - "user_event": { - "revoke": { - "date_time": "2018-05-24T09:48:12+00:00", - "target": { - "app_id": "13090192" - }, - "source": { - "user_id": "63046977" - } - } - } -} -``` - -#### direct_message_events - -``` -{ - "for_user_id": "4337869213", - "direct_message_events": [{ - "type": "message_create", - "id": "954491830116155396", - "created_timestamp": "1516403560557", - "message_create": { - "target": { - "recipient_id": "4337869213" - }, - "sender_id": "3001969357", - "source_app_id": "13090192", - "message_data": { - "text": "Hello World!", - "entities": { - "hashtags": [], - "symbols": [], - "user_mentions": [], - "urls": [] - } - } - } - }], - "apps": { - "13090192": { - "id": "13090192", - "name": "FuriousCamperTestApp1", - "url": "https://x.com/furiouscamper" - }, - "users": {}, - "3001969357": { - "id": "3001969357", - "created_timestamp": "1422556069340", - "name": "Jordan Brinks", - "screen_name": "furiouscamper", - "location": "Boulder, CO", - "description": "Alter Ego - X PE opinions-are-my-own", - "url": "https://t.co/SnxaA15ZuY", - "protected": false, - "verified": false, - "followers_count": 22, - "friends_count": 45, - "statuses_count": 494, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg" - }, - "4337869213": { - "id": "4337869213", - "created_timestamp": "1448312972328", - "name": "Harrison Test", - "screen_name": "Harris_0ff", - "location": "Burlington, MA", - "protected": false, - "verified": false, - "followers_count": 8, - "friends_count": 8, - "profile_image_url": "null", - "statuses_count": 240, - "profile_image_url_https": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png" - } - } -} -``` - -#### direct_message_indicate_typing_events - -``` -{ - "for_user_id": "4337869213", - "direct_message_indicate_typing_events": [{ - "created_timestamp": "1518127183443", - "sender_id": "3284025577", - "target": { - "recipient_id": "3001969357" - } - }], - "users": { - "3001969357": { - "id": "3001969357", - "created_timestamp": "1422556069340", - "name": "Jordan Brinks", - "screen_name": "furiouscamper", - "location": "Boulder, CO", - "description": "Alter Ego - X PE opinions-are-my-own", - "url": "https://t.co/SnxaA15ZuY", - "protected": false, - "verified": false, - "followers_count": 23, - "friends_count": 47, - "statuses_count": 509, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg" - }, - "3284025577": { - "id": "3284025577", - "created_timestamp": "1437281176085", - "name": "Bogus Bogart", - "screen_name": "bogusbogart", - "protected": true, - "verified": false, - "followers_count": 1, - "friends_count": 4, - "statuses_count": 35, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/763383202857779200/ndvZ96mE_normal.jpg" - } - } -} -``` - - -#### direct_message_mark_read_events - -``` -{ - "for_user_id": "4337869213", - "direct_message_mark_read_events": [{ - "created_timestamp": "1518452444662", - "sender_id": "199566737", - "target": { - "recipient_id": "3001969357" - }, - "last_read_event_id": "963085315333238788" - }], - "users": { - "199566737": { - "id": "199566737", - "created_timestamp": "1286429788000", - "name": "Le Braat", - "screen_name": "LeBraat", - "location": "Denver, CO", - "description": "data by day @X, design by dusk", - "protected": false, - "verified": false, - "followers_count": 299, - "friends_count": 336, - "statuses_count": 752, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/936652894371119105/YHEozVAg_normal.jpg" - }, - "3001969357": { - "id": "3001969357", - "created_timestamp": "1422556069340", - "name": "Jordan Brinks", - "screen_name": "furiouscamper", - "location": "Boulder, CO", - "description": "Alter Ego - X PE opinions-are-my-own", - "url": "https://t.co/SnxaA15ZuY", - "protected": false, - "verified": false, - "followers_count": 23, - "friends_count": 48, - "statuses_count": 510, - "profile_image_url": "null", - "profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg" - } - } -} -``` - -#### tweet_delete_events - -``` -{ - "for_user_id": "930524282358325248", - "tweet_delete_events": [ -{ - "status": { - "id": "1045405559317569537", - "user_id": "930524282358325248" - }, - "timestamp_ms": "1432228155593" - } - ] -} -``` - -## Account Activity Replay API - -`Enterprise` - -The Account Activity Replay API is a data recovery tool that allows you to retrieve events from as far back as five days. It should be utilized to recover data in scenarios where your [webhook](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) server misses events, -- whether due to disconnections lasting longer than the [retry window](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#retries), or for those disaster recovery scenarios where you need a few days to restore your system back to normal. - -The Account Activity Replay API was developed for any scenario where you fail to ingest [activities](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) for a period of time. It delivers activities to the same webhook used for the original real-time delivery of activities. This product is a recovery tool and not a backfill tool, which means events will only be replayed if a previous delivery of them was attempted. The Account Activity Replay API cannot deliver events for a time period prior to a subscription’s creation time. - -### Using Account Activity Replay API - -If your account is configured with Replay functionality, you can make requests in a similar manner as requests to the Account Activity API. It is important to note that your request must specify a webhook id parameter to indicate which webhook’s activities you would like to replay. In other words, a Replay request asks Account Activity Replay API to retrieve events from a start date and time to an end date and time based on the webhook id and application id. - -Please note that UTC time is expected. These activities are delivered through the registered webhook associated with the id at a rate of up to 2,500 events per second. Also keep in mind that only one Replay job per webhook may be running at a time, although all subscriptions that were active during the date/time specified on that webhook will be replayed. - -Events are delivered beginning with the first (oldest) minute of the specified time period, continuing chronologically (as best as possible) until the final minute is delivered. At that point, Replay will deliver a [job completion event](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#job-completed-successfully-message) to the webhook. Because we work chronologically in delivering activities, if there are little or no matching results near the start time, there will likely be a period of time before the first results are delivered. - -### Limitations - -Replay is intended as a tool for easily recovering activities as far back as five days ago, but it will not deliver events prior to a subscription’s creation time. For example, if three days ago, you added a new subscription and ran a Replay job with a window for five days prior to today, you would only receive data for the three days that this new subscription was active. - -### Data availability and types - -Activities from the Account Activity Replay API are available five days from the initiation of the request, with new data becoming available roughly 10 minutes after a given activity is created. You will be able to make requests specifying a timeframe within this five day window using the from\_date and to\_date parameters within the request. Events that were originally delivered prior to having access to Replay cannot be replayed. For example, if your account was enabled for access to the Account Activity Replay API on June 1, 2019 at 3:30PM UTC, you would not be able to use Replay to retrieve any events prior to that date and time. - -Continue to the [Account Activity Replay API reference](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) - -## Migration introduction - -**We retired the Site Streams, User Streams, and standard beta version of the Account Activity API - DM Only products in 2018. If you had been using those products, please make sure to migrate over to the premium or enterprise version of the Account Activity API.** - -**We have also retired the legacy Direct Message endpoints. If you had been using those endpoints, please make sure to migrate over to either the new DM endpoints, or to the premium or enterprise version of the Account Activity API. ** - -**Please review [this announcment](https://devcommunity.x.com/t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746) to learn more.** - -Here are the endpoints that will be affected by these changes: - -* User Streams -* Site Streams -* GET direct_messages -* GET direct_messages/sent -* GET direct_messages/show -* POST direct_messages/new -* POST direct_messages/destroy -   - -We have new endpoints and services available that provide similar access and, for Direct Messages, some additional functionality: - -* Account Activity API [enterprise](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) and [premium](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-api-reference-index) -* [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) -* [GET direct_messages/events/show](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) -* [POST direct_messages/events/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) -* [POST direct_messages/events/destroy](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/delete-message-event) - -To help you make a smooth migration to these new endpoints and services we have two migration guides: - -* [Account Activity API migration guide](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-guide-moving-from-user-streams-site-streams-to-account-activity-api) for those going from User Streams and Site Streams to our new webhooks based service -* [Direct Message migration guide](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/guides/direct-message-migration) for those migrating between Direct Message REST endpoints -   - -Additionally, we have a [series of videos](https://www.youtube.com/playlist?list=PLFKjcMIU2WshGG6Yj940XM7Z6BFs1zfBg) about the Account Activity API and how to get started. - -And, finally, we have code samples to further your understanding and help you get started quickly: - -* The [Account Activity Dashboard](https://github.com/xdevplatform/Account-Activity-dashboard) is a sample Node.js web app with helper scripts to get started with the Account Activity API. -* [SnowBot](https://github.com/xdevplatform/SnowBotDev) is a sample chatbot using the Account Activity API and REST Direct Message endpoints. It’s written in Ruby, uses the Sinatra web app framework, and is deployed on Heroku. - - -## Migration Guide: Moving from User Streams/Site Streams to Account Activity API - -**As of August 23rd, 2018, we retired both Site Streams and User Streams. Please make sure to migrate over to the Account Activity API.** - -**Please review [this announcement](https://devcommunity.x.com/t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746) to learn more.** - -This guide is designed to help you migrate from legacy User Streams and Site Streams APIs to their replacement, the Account Activity API. Below you will find a summary of the changes, new features list, as well as key differences and considerations to help with the transition. For guidance in migrating from basic DM endpoints, please refer to the [Direct Message migration guide](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/guides/direct-message-migration). - -### Summary of changes - -The Account Activity API will deliver you events for authenticated and subscribed accounts via webhooks as opposed to a streaming connection like with User Streams and Site Streams. - -#### Deprecated APIs - -GET user - -GET site  (including control streams: GET site/c/:stream\_id,  GET site/c/:stream\_id/info.json,  GET site/c/:stream\_id/friends/ids.json,  POST site/c/:stream\_id/add\_user.json,  POST /site/c/:stream\_id/remove_user.json) - -#### Replacement APIs - -[Enterprise Account Activity API - All Activities](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) - -### Differences & migration considerations - -**API format:** The new Account Activity API operates differently than User Streams and Site Streams. You will need to alter your web app to receive data with webhooks. You can find more information on webhooks [here](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks). - -**Data Available:** Another key difference you will notice is in regards to the data being delivered. X will no longer send events from people that you follow on X (aka your home timeline). This was an intentional change and is not something we plan to alter going forward. - -**Reliability:** Unlike streaming, webhooks enable confirmation of delivery and options to retry POSTed activities that do not make it to the webhook URL.  This gives more assurance that the app is receiving all applicable activities, even if there are brief disconnections or periods of downtime. - - -### New features - -The Account Activity API offers many new features, most notably that data is now delivered via webhooks as opposed to streaming. Webhooks offer many benefits compared to streaming, but the most prominent are speed and reliability. The API will send you data in the form of JSON events as they become available and you will no longer need to maintain an active connection or poll the endpoint. This limits the need for redundancy features and increases efficiency overall. More information on webhooks can be found in the [technical documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks). - - -### Managing user subscriptions - -The Account Activity API allows multiple subscriptions for a single registered webhook.  This allows multiple user subscriptions activities to be delivered to the same location, similar to the Site Streams architecture, with webhooks.  This means you can track subscriptions, as they pertain to your subscription limits, independently from the webhook connection.  This also allows scalability from only one or a few subscriptions to thousands of subscriptions for a single webhook. - -### **How to Migrate** - -### **Follow the steps below to easily migrate from the Site Streams API to the Account Activity API** - -**Step 1: Decide on a Package** - -Depending on how you are currently operating with User Streams or Site Streams, you should consider moving to either the enterprise or premium version of the Account Activity API.  Consider the number of applications or authorized users you are currently supporting and scale appropriately to the volume and reliability needed.  When deciding on the package that best suits your needs, some things worth considering are: - -* Number of webhooks needed -* Current/projected subscriptions/authorized users managed on your application -* Current number of X client applications -* The level of support you'd prefer from X (forum support or managed enterprise level 1:1 support) -* Price of each package - -**Step 2:** **Check the Setup of your X app in the Developer Console** - -The [X app](/resources/fundamentals/developer-apps) currently used for User Streams or Site Streams will be listed for the owning user within the [Developer Console](/resources/fundamentals/developer-portal). This X app can also be used for Account Activity API to retain authorized users for that application.  A new app can also be created, and users can be re-authorized for this new app if desired.  If you are creating a new app on behalf of a business, it is recommended that you create the app with a corporate X @handle account. - -* Enable “Read, Write and Access direct messages” on the [permissions](/resources/fundamentals/developer-apps#app-permissions) tab of your X app page.  - *Note that changing these settings is not retroactive, any authorized users will keep the authorization settings from the time at which they were authorized. If a user has not already given you read, write and direct message access, you will need to have that user re-authorize your application. -* If you are unfamiliar with [X Sign-in](/resources/fundamentals/authentication#log-in-with-x) and how user contexts work with the X API review [Obtaining Access Tokens](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks). -* Generate access tokens for the X app owner at the bottom of the “Keys and Tokens” tab. On this same tab take note of your Consumer Key, Consumer Secret, Access Token and Access Token Secret. You will need these to use the API. -* Generate a bearer token using your Consumer Key and Consumer Secret for [application-only](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only) API methods. - -**Step 3: Setup & Configure Your Webhooks** - -* Create a web app with an endpoint to use as your webhook to receive events (e.g. https://your\_domain.com/webhook/twitter or https://webhooks.your\_domain.com). -* Use your Consumer Key, Consumer Secret, Access Token and Access Token Secret when creating your webhook, Note that your endpoint must return a JSON response with a response\_token that is a base64 encoded HMAC SHA-256 hash created from the crc\_token and your app Consumer Secret. - -* Review [Securing Webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#securing-webhooks) documentation taking special note of the Challenge Response Check (CRC) requirements. -* Make sure your webhook supports POST requests for incoming events and GET requests for the CRC. -* Make sure your webhook has low latency (\<3 seconds to respond to POST requests) - -**Step 4: Validate Your Webhook Setup** - -* Webhook APIs will secure your webhooks in two ways: - -               \- Require challenge response checks to validate that the webhook owner is the web app owner. - -               \- A signature header in each POST request for your web app to validate the source. - -* In order to verify that you are both the owner of the web app and the webhook URL, X will perform a Challenge Response Check (CRC), which is not to be confused with a cyclic redundancy check. -* A GET request with a parameter named crc\_token will be sent to your webhook URL. Your endpoint must return a JSON response with a response\_token that is a base64 encoded HMAC SHA-256 hash created from the crc_token and your app Consumer Secret. -* The crc\_token should be expected to change for each incoming CRC request. The crc\_token should be used as the message in the calculation, where your Consumer Secret is the key. -* In the event that the response is invalid, events will cease to be sent to the registered webhook. - -**Step 5: Create Subscriptions for Each User Stream or Site Streams Authorized User** - -Converting to the Account Activity API from User Streams: - -* Generate a list of your current user subscriptions on User Streams -* Set up your new Account Activity API subscriptions using the request:  _POST account\_activity/all/:env\_name/subscriptions_ -* Confirm your Account Activity API subscriptions using the request:  _GET account\_activity/all/:env\_name/subscriptions/list -  _ - -Converting to the Account Activity API from Site Streams: (using control streams): - -* Generate a list of your current subscriptions on Site Streams using the request:  _GET /1.1/site/c/:stream_id/info.json_ -* Set up your new Account Activity API subscriptions using the request:  _POST account\_activity/all/:env\_name/subscriptions_ -* Confirm your Account Activity API subscriptions using the request:  _GET account\_activity/all/:env\_name/subscriptions/list -  _ - -Registering a Webhook and Creating Subscriptions (not migrating from Site Streams or User Streams) - -* Register your webhook URL with your app using [POST webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) and receive a webhook_id. -* Use the returned webhook_id to add user subscriptions with [POST webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all). - -### The Account Activity dashboard (sample Account Activity API application) - -We've created a sample app to make testing the Account Activity API a little quicker:    - -* Download the Account Activity Dashboard sample application [here](https://github.com/xdevplatform/Account-Activity-dashboard) (it uses Node.js) -* Follow the instructions on the README to install and launch the app -* Once the application has been launched, you can use the UI to easily set up your webhook and create a new subscription - -### Available Activities - -| Message Type | Details | -| :--- | :--- | -| [tweet\_create\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#tweet-create-events-posts-retweets-replies-quotetweets) | Post status payload when any of the following actions are taken by or to the subscription user: Posts, Retweets, Replies, @mentions, QuoteTweets | -| [favorite_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#favorite-events) | Favorite (like) event status with the user and target. | -| [follow_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#follow-events) | Follow event with the user and target. | -| [block_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#block-events) | Block event with the user and target. | -| [mute_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#mute-events) | Mute event with the user and target. | -| [direct\_message\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-events) | Direct message status with the user and target. | -| [direct\_message\_indicate\_typing\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-indicate-typing-events) | Direct message typing event with the user and target. | -| [direct\_message\_mark\_read\_events](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#direct-message-mark-read-events) | Direct message read event with the user and target. | - -### Deprecated streaming message types  - -| | | -| :--- | :--- | -| Blank lines | Blank lines will no longer be delivered in the Account Activity API as they were used as keep-alive messages in User Streams and Site Streams. | -| Limit notices | Limit notices will no longer be sent to a given webhook.  Instead, users can call the API to get current usage of available handles. This will be included in the Developer Console at some time in the future. | -| Disconnect messages | Disconnect notices will no longer be necessary as webhooks do not rely on an active connection. | -| Stall warnings | Stall warnings will no longer be necessary as webhooks do not rely on an active connection being able to handle large numbers of incoming messages. | -| Friends list | Friends lists will no longer be sent proactively. There will now be a REST endpoint to get this information. | - -### Deprecated event types - -| | | | | | -| :--- | :--- | :--- | :--- | :--- | -| **Description** | **Event Name** | **Source** | **Target** | **Target Object** | -| User deletes a Post | delete | Current user | Current User | Post | -| Followed user deletes a Post | delete | Followed user | Followed user | Post | -| User unfavorites a Post | unfavorite | Current user | Post author | Post | -| User’s Post is unfavorited | unfavorite | Unfavoriting user | Current user | Post | -| User unfollows someone | unfollow | Current user | Followed user | Null | -| User creates a list | list_created | Current user | Current user | List | -| User deletes a list | list_destroyed | Current user | Current user | List | -| User edits a list | list_updated | Current user | Current user | List | -| User adds someone to a list | list\_member\_added | Current user | Added user | List | -| User is added to a list | list\_member\_added | Adding user | Current user | List | -| User removes someone from a list | list\_member\_removed | Current user | Removed user | List | -| User is removed from a list | list\_member\_removed | Removing user | Current user | List | -| User subscribes to a list | list\_user\_subscribed | Current user | List owner | List | -| User’s list is subscribed to | list\_user\_subscribed | Subscribing user | Current user | List | -| User unsubscribes from a list | list\_user\_unsubscribed | Current user | List owner | List | -| User’s list is unsubscribed from | list\_user\_unsubscribed | Unsubscribing user | Current user | List | -| User updates their profile | user_update | Current user | Current user | Null | -| User updates their protected status | user_update | Current user | Current user | Null | - - -## Direct Message migration guide - -**On September 17th, 2018 we retired the legacy Direct Message endpoints. -If you had been using those endpoints, please make sure to migrate over to the new Direct Message endpoints or the Account Activity API.** - -**Please review [this announcment](https://devcommunity.x.com//t/details-and-what-to-expect-from-the-api-deprecations-this-week-on-august-16-2018/110746) to learn more.** - -This guide is designed to help you migrate from legacy Direct Message REST APIs to their enhanced replacements which have graduated from beta. Below you will find a summary of the changes, a new features list, and key differences and considerations to help with the transition. The new Direct Message endpoints are available now to all developers. For guidance in migrating from User Streams or Site Streams, see the [migration guide to Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#migration-guide-moving-from-user-streams-site-streams-to-account-activity-api). - -* [Summary of changes](#summary) -* [New features](#features) -* [Sending Direct Messages](#sending) -* [Receiving Direct Messages](#receiving) -* [Deleting Direct Messages](#deleting) - -### Summary of changes - -If you are still using the following DM endpoints, you will have to migrate to the newer endpoints.  - -| Deprecated endpoint | New migration alternative | -| :--- | :--- | -| [POST direct_messages/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) | [POST direct_messages/events/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) | -| [GET direct_messages/show](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) | [GET direct_messages/events/show](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) | -| [GET direct_messages](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) | [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) | -| [GET direct_messages/sent](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) | [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) | -| [POST direct_messages/destroy](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/delete-message-event) | [DELETE direct_messages/events/destroy](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/delete-message-event "GET direct_messages/events/list") | - -### New features - -The new Direct Message API endpoints support a number of new capabilities and provide improved access to previous Direct Messages. New features include: - -* Support for media attachments (image, GIF, and video). -* Ability to prompt users for structured replies with a predefined options list. -* Up to 30 days of access to past Direct Messages. - -For a full list of new Direct Message features and additional new API endpoints refer to the [technical documentation](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/overview). -  - -### Differences & migration considerations - -The new API endpoints behave very differently from their previous counterparts. Simply updating the endpoint URLs will result in errors in your application. Consider the following when updating your application for the migration. - -#### New Direct Message object - -The first thing you are likely to notice is the new object structure of Direct Messages. This new Message Create object structure has been introduced to support new capabilities like [Quick Replies](https://developer.x.com/en/docs/x-api/v1/direct-messages/quick-replies/overview) and [Attachments](https://developer.x.com/en/docs/x-api/v1/direct-messages/message-attachments/overview). The new object also contains a smaller condensed user object. Your application will need to be updated to account for this new object structure when parsing and potentially in data models or storage. For descriptions of each property see the [full documentation on the Message Create Object](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/guides/message-create-object). - -**Example message create object** - -```json -{ - "type": "message_create", - "id": "1234858592", - "created_timestamp": "1392078023603", - "initiated_via": { - "tweet_id": "123456", - "welcome_message_id": "456789" - }, - "message_create": { - "target": { - "recipient_id": "1234858592" - }, - "sender_id": "3805104374", - "source_app_id": "268278", - "message_data": { - "text": "Blue Bird", - "entities": { - "hashtags": [], - "symbols": [], - "urls": [], - "user_mentions": [], - }, - "quick_reply_response": { - "type": "options", - "metadata": "external_id_2" - }, - "attachment": { - "type": "media", - "media": { - ... - } - } - } - } -``` -#### Summary - -* Entirely new Direct Message object structure. -* Condensed user object. -* New information provided (quick reply responses, attachments, etc). - - - -### Sending Direct Messages - -[POST direct_messages/events/new](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/new-event) is a direct replacement for sending Direct Messages. The most significant difference with this endpoint is that all information is now sent as JSON in the POST request body as opposed to individual POST params. - -**Example Twurl request** -```bash -twurl -A 'Content-type: application/json' -X POST /1.1/direct\_messages/events/new.json -d '{"event": {"type": "message\_create", "message\_create": {"target": {"recipient\_id": "4534871"}, "message_data": {"text": "Hello World!"}}}}' -``` -Note in the above request that the content-type is set to application/json as opposed to application/x-www-form-urlencoded. Additionally, if you are constructing the OAuth 1.0a signature, note that the JSON body is not included in the generation of the signature. Most OAuth libraries already account for this. If you are using [twurl](https://github.com/twitter/twurl), ensure you are using at least version 0.9.3. - -#### Summary - -* Message is defined in JSON POST body -* Content-type header must be set to application/json -* JSON body is not included in the generation of the OAuth signature. -   - -### Retrieving Direct Messages - -Retrieving past Direct Message is now accomplished with a single API endpoint: [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events). The significant difference with this new endpoint is that it now returns both sent and received messages in reverse chronological order. This may make it easier to rebuild a conversation. However, if you are only looking for sent or received messages you will need to post-process the response by referring to the sender_id property. - -Pagination is now based on a cursor value rather an ID of a Direct Message. A cursor property is returned with each response. [GET direct_messages/events/list](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/list-events) will return up to 30 days of past messages, regardless of how many messages exist within the past 30 days. When a cursor is not returned, there are no more messages to be returned. The method for accessing individual Direct Messages with [GET direct_messages/events/show](https://developer.x.com/en/docs/x-api/v1/direct-messages/sending-and-receiving/api-reference/get-event) remains the same, although the Direct Message object returned has a different structure as described previously. - -Finally, real-time access to Direct Messages will now be accomplished via webhook with the [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity). For guidance in migrating from User Streams or Site Streams, see the migration guide to Account Activity API for more information. - -#### Summary - -* Sent and Received messages are now returned on the same endpoint. -* Up to 30 days of messages returned. -* Cursor based pagination. -* Real-time access to Direct Message via webhook. - -### Deleting Direct Messages - -Direct Messages can now be deleted with DELETE direct_messages/events/destroy. The interface is largely the same requiring the ID of the message to delete. The key differences is the endpoint now requires a DELETE request instead of a POST request. - -How deleted Direct Messages are reflected in official X clients remains the same. Direct Messages are only removed from the interface of the user context provided. Other members of the conversation can still access the Direct Message. - -#### Summary - -* Deleting a Direct Message requires the ID. -* New endpoint requires a DELETE request. -* How deleted Direct Messages are reflected in official X clients remains unchanged. - -**Questions about migrating to the new Direct Message endpoints? -**Post your question to the developer community forum on [devcommunity.com](https://devcommunity.x.com/). - - -## Frequently Asked Questions - -### General - -**What are the advantages of using the Account Activity API?** - -The Account Activity API uses webhooks, meaning that unlike for the streaming APIs we don't require you to have an open connection for us to send you information. Webhooks are also different from Rest APIs because you don't have to pull us hundreds of times every 15 minutes to get the data you care about. This increases the efficiency between a user and your app, as it delivers data when it happens. - -The Account Activity API has a number of benefits: - -1. **Speed**: we deliver data at the speed of X. -2. **Simplicity**: we deliver all of an account's events, through one single webhook connection. The activities delivered in the API include Posts, @mentions, replies, Retweets, Quote Tweets, Retweets of Quote Tweets, favorites, Direct Messages sent, Direct Messages received, follows, blocks, mutes.  -3. **Scale**: you receive all of the activities for an account that you manage without being restricted by any rate limits of event caps. - -The Account Activity API is available as a premium sandbox, premium paid, and enterprise offering, so you can scale as you require more accounts for liability features or additional functionality. - -To get started, download sample code snippets from [GitHub](https://github.com/xdevplatform/account-activity-dashboard). -  - -**How do I identify which product tier is best for me?** - -Please read through our [Account Activity API Overview](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) page to learn more about the differences between the Premium options and the Enterprise option.  -  - -**What is the difference between a Premium environment and an Enterprise webhook?** - -There is no difference. Each Premium environment will have its own webhook_id. -  - -**I need a development, staging and production environment for Account Activity API, is this possible?** - -Yes! With the paid tiers of Account Activity API (Paid Premium and Enterprise), it's possible to register multiple webhook URLs and manage subscriptions separately for each through the API methods. Additionally, multiple client apps may be added to an allowlist to maintain authorization for your current authorized users. -  - -**Do you have any step-by-step guides on how to get set up with the Account Activity API?** - -As a matter of fact, we do! - -* If you are just getting started, we recommend that you visit our [Getting started with webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks) guide - -* Follow along with our X Dev supported scripts:  - * [Account Activity API dashboard](https://github.com/xdevplatform/account-activity-dashboard), a node web app that displays webhook events. - * The [SnowBot chatbot](https://github.com/xdevplatform/SnowBotDev), a Ruby web app built on the Account Activity and Direct Message APIs. This code base includes a [script](https://github.com/xdevplatform/SnowBotDev/wiki/Account-Activity-API-setup-script) to help set up Account Activity API webhooks. -   - -**Is there a way to recover data if our system goes down for a period of time?** - -With the paid tiers of Account Activity API (Paid Premium and Enterprise), our system will [retry](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#retries) to send the activities to you several times over a four hour period. If your system does not respond within that four hour period, then the activity will be lost and you will have to use other REST endpoints to recover data within 7 days. - -We suggest that you use your different webhooks, or environments, as a redundancy tool like the [Account Activity Replay API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-replay-api) to ensure that you don't miss any activities if one of your systems goes down. -  - -**What authentication do I have to use with the Account Activity API?** - -The authorization methods required for Account Activity API is described per method in the [API reference pages](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-api-reference-index). If you are just starting out with X authentication, we recommend that you read through [this section](/resources/fundamentals/authentication). - - -**What is a challenge-response check (CRC)?** - -The Account Activity API challenge response check is a security feature put in place to ensure that the Account Activity API’s activities are being sent to the proper developer. It also can be used by developers to ensure that the data that they are receiving is coming from X. X will automatically send a CRC to your webhook URL once every 24 hours, starting the last time the webhook URL was validated. Your system must respond with a valid response within 3 seconds to remain validated.  - -Please visit our page [Securing webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#securing-webhooks) for more details. -  - -**Is there anything that would immediately invalidate my webhook URL?** - -If one of the following occurs, we will immediately mark your webhook as invalid: - -* The server responds to a CRC with an incorrect token. In this case, our system will not [retry](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#retries) to send you the activity. -* The webhook URL has an incorrect certificate configured. In this case, our system will not [retry](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#retries) to send you the activity. -* Your server returning a non-2XX, non-4XXX, non-5XXX response code. -* You specify the use of gzip without actually sending it. -* You do not specify the use of gzip, but actually send it in the response. -   - -**Will I get duplicate activities if subscribed to users that are interacting with each other?** - -Yes.  If your web app has active subscriptions for User A and User B, and User A mentions User B in a Post, there will be two POST activities sent to the registered webhook.  Each activity will have an indicator of "for\_user\_id" to show which subscription the activity belongs to. -  - -**When I make a subscription to my webhook, can I replace the `/all/` portion of the following endpoint with other account activity data objects to limit the activities the API delivers? **`POST https://api.x.com/1.1/account_activity/all/:env_name/subscriptions.json` - -No, this is not possible. As it currently stands, we only have the `/all/` product available. -  - -**Is there any way of using the Account Activity API without requesting Direct Messages permissions from users? ** - -At this point, Direct Messages permissions are required because there is no way to 'filter out' the Direct Messages activities for this API.  -  - -**Is there a sandbox version of the Account Activity API?** - -Yes, we offer a sandbox option for testing. Our sandbox option is limited to a single webhook with a limit of a maximum of 15 subscriptions. You can read more about the sandbox option in [our documentation](/x-api/enterprise-gnip-2.0/fundamentals/account-activity).  - - -**Is it possible to use the Account Activity API to get Retweets of Posts that mention subscribed users? ** - -Unfortunately, this is not part of the activities delivered with this API. For this, we suggest using the Streaming API instead.  -  - -**What are the possible activity types that are represented by a tweet\_create\_event?** - -A tweet\_create\_event payload will be sent: - -If the subscription user does any of the following actions: - -* Creates a Post -* Retweets -* Replies to a Post - -If another user: - -* @mentions* the subscription user -* Quotes a Tweet created by the subscription user  - -*Note: The Account Activity API only delivers events when the subscription user would receive a notification from X and could see the event publicly.  This means, If the mentioned account (@userA) follows the protected account (@userB) then UserA will get a notification UserB mentioned them. If UserA is not following UserB (and approved by UserB) UserA will not get a notification, and therefore a tweet\_create\_event would not be sent via AAA if @userA had a subscription. - -**If a blocked user mentions my subscribed user, how can I identify this?** - -You will see a boolean field \`user\_has\_blocked\` on the top level of the json response, set to either “true” or “false". This field will only be exposed on Post mentions.  - -Enterprise - -**How can I add my app to an allowlist or check if my app is already on the allowlist?** - -To manage the [X apps](/resources/fundamentals/developer-apps) that you have added to an allowlist for access via the Enterprise APIs, please reach out to your account manager with your app ID. You can find your app ID by navigating to the ["Apps"](/resources/fundamentals/developer-apps) page in the [Developer Console](/resources/fundamentals/developer-portal). -  - -**If I have access to three webhooks, can I use three webhooks for each of the apps that I have registered for enterprise use?** - -The webhook limit is set on the account level, not the app level. If you have access to three webhooks and two apps registered for enterprise use, you can use two webhooks on one app and the third on the other app, but not three on each app.  - - -**Can I specify which types of events will be redelivered using the Account Activity Replay API?** - -The types of events to replay cannot be specified. All events delivered during the date and time window specified will be replayed.  - - -**Will there be any retries if my application fails to ingest an Account Activity Replay API event?** - -No, there will not be any retries. If an application fails to ingest an event sent by the Account Activity Replay API, another Replay job can be submitted for the same time period to attempt redelivery of any missed Replay events.  - - -**What should I do when I receive a partial success completion event?** - -We suggest making note of the timestamps for the events that were received and requesting another Replay job for the events that were missed.  - - -**How many Account Activity Replay API jobs can I have running at a time?** - -Only one Account Activity Replay API job per webhook may be running at a time.  - - -**How can I differentiate Account Activity Replay API events from real-time production events as they are delivered to my webhook?** - -Since the Account Activity Replay API will always deliver events from the past, events can be differentiated from real-time production events based on the event’s timestamp.  - - -**How soon can I start using the Account Activity Replay API to redeliver an activity my application dropped or missed?** - -An activity becomes available for redelivery about 10 minutes after it was created.  - -### Error troubleshooting guide - -#### Code 32 - -This error generally means that something is either malformed in the request, headers, authorization, or url that you are specifying. This is not an Account Activity API error, it’s an authorization error and X isn’t getting the proper Oauth setup or url. - -* **Enterprise** \- Make sure the consumer keys and access tokens you are using belong to a [X app](/resources/fundamentals/developer-apps) that has been registered for use of Enterprise products. If you don't have your consumer keys and access tokens, or need to add your X app to the allowlist, please reach out to your account manager.  - -* If authenticating with user context, make sure you have properly [authorized your request](/resources/fundamentals/authentication#authorizing-a-request) with the proper `oauth nonce`, `oauth_signature`, and `oauth_timestamp`. - -* Make sure that your access tokens have the proper permission level. - * When on the 'Keys and tokens' tab in the [app dashboard](/resources/fundamentals/developer-apps), please make sure that your access tokens have the 'Read, write, and direct messages' [permission level](/resources/fundamentals/developer-apps#app-permissions).  - * If the tokens' permission level is set to anything less than this, please navigate to the 'Permissions' tab, adjust the access permission to 'Read, write, and direct messages', then regenerate your access tokens and secret from the 'Keys and tokens' tab. - -* Make sure that your URL is formed properly. - * Please keep in mind that `:env_name` is case sensitive. -   - -#### Code 200 - Forbidden - -* **Premium** \- Make sure that you have an approved [developer account](/resources/fundamentals/developer-portal) before you try to make a request to the API. You also must use the proper :env_name in the request, which you can setup on the [dev environments](/resources/fundamentals/developer-portal) page. - -* **Enterprise** \- Make sure that your account manager has set you up with access to the Account Activity API. -* Make sure you have set up your URI properly. This error can trigger if you have entered the incorrect URI in your request. -   - -#### Code 214 - Webhook URL does not meet the requirements. - -* Please make sure that you are using https. -* Your webhook URL could be malformed. -* Learn more about how to set up your webhook URL under the [Develop webhook consumer app](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#3-develop-webhook-consumer-app) section on [Getting started with webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#getting-started-with-webhooks) page. -   - -#### Code 214 - High latency on CRC GET request. Your webhook should respond in less than 3 seconds. - -* This means that your server is slow. Make sure that you are responding to the CRC within 3 seconds. -   - -#### Code 214 - Non-200 response code during CRC GET request (i.e. 404, 500, etc). - -* Your server is down. Make sure that your server is running properly. -   - -#### Code 214 - Too many resources already created. - -* **Enterprise** \- You have already used all of your webhooks. Use the [GET webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) endpoint with each of your registered apps to identify where your webhooks are distributed.  - - - -#### Code 261 - Application cannot perform write actions. - -* The app that you are using with the API does not have the proper [permission level](/resources/fundamentals/developer-apps#app-permissions) set for its access token and access token secret. Please navigate to the 'Keys and tokens' tab on the [X apps](/resources/fundamentals/developer-apps) dashboard and check the permission levels assigned to your access token and access token secret. If it is set to anything other than 'Read, write and Direct Messages,' then you are going to have to adjust the settings under the 'Permission' tab and regenerate your access token and access token secret to apply the new settings. -* Alternatively, you are trying to register a webhook using app-only authentication, which is not supported. Please authenticate with user context instead as noted in the API reference sections for registering a webhook for [Enterprise Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks). - - -## Account Activity API Reference Index - -| | | -| :--- | :--- | -| **Purpose** | Enterprise | -| Registers a webhook URL / Generates a webhook_id | [POST
webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#enterprise-account-activity-api) | -| Returns all webhook URLs and their statuses | [GET
webhooks](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks) | -| Manually triggers a challenge response check | [PUT
webhooks/:webhook_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#put-account-activity-webhooks-webhook-id) | -| Subscribes an application to an account's events | [POST
webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#post-account-activity-webhooks-webhook-id-subscriptions-all) | -| Returns a count of currently active subscriptions | [GET
subscriptions/count](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | -| Check to see if a webhook is subscribed to an account | [GET
webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-webhooks-webhook-id-subscriptions-all) | -| Returns a list of currently active subscriptions | [GET
webhooks/:webhook_id/subscriptions/all/list](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#get-account-activity-subscriptions-count) | -| Deletes the webhook | [DELETE
webhooks/:webhook_id](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id) | -| Deactivates a subscription using 3-legged OAuth (DEPRECATED) | [DELETE
webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) | -| Deactivates a subscription using application-only OAuth | [DELETE
webhooks/:webhook\_id/subscriptions/:user\_id/all.json](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json) | -| Redelivers activities to a webhook | [POST
replay/webhooks/:webhook_id/subscriptions/all](/x-api/enterprise-gnip-2.0/fundamentals/account-activity#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated) | - - -### Enterprise Account Activity API - -#### POST account_activity/webhooks[](#post-account-activity-webhooks "Permalink to this headline") - -Registers a new webhook URL for the given application context. The URL will be validated via CRC request before saving. In case the validation failed, returns comprehensive error message to the requester. - -The number of allowed webhooks is determined by billing package. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (user context - all consumer and access tokens) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 15 | -| Support for Tweet edits | All Tweet objects will include Tweet edit metadata describing the Tweet's edit history. See the ["Tweet edits" fundamentals](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) page for more details. | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| url (required) | Encoded URL for the callback endpoint. | - -### Example Request[](#example-request "Permalink to this headline") - - $ curl --request POST - --url 'https://api.x.com/1.1/account_activity/webhooks.json?url=https%3A%2F%2Fyour_domain.com%2Fwebhooks%2Ftwitter%2F0' - --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"' - -### HTTP Responses[](#http-responses "Permalink to this headline") - -| HTTP Code | Message | -| :--- | :--- | -| 200 | Webhook URL is registered to the provided application | -| 403 | There is an error with your request. See error messages section below. | - -### Example Response - Success[](#example-response-success "Permalink to this headline") -```json -_HTTP 200_ - - { - "id": "1234567890", - "url": "https://your_domain.com/webhook/twitter/0", - "valid": true, - "created_at": "2016-06-02T23:54:02Z" - } -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 214 | Webhook URL does not meet the requirements. | -| 214 | Too many resources already created. | -| 214 | Webhook URL does not meet the requirements. Invalid CRC token or json response format. | -| 214 | High latency on CRC GET request. Your webhook should respond in less than 3 seconds. | -| 214 | Non-200 response code during CRC GET request (i.e. 404, 500, etc). | - -_HTTP 403_ -```json - { - "errors": [ - { - "code": 214, - "message": "Too many resources already created." - } - ] - } -``` -#### GET account_activity/webhooks[](#get-account-activity-webhooks "Permalink to this headline") - -Returns all URLs and their statuses for the given application. - -We mark a URL as invalid if it fails the daily validation check. In order to re-enable the URL, call the update endpoint. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (application only - bearer token) | -| Rate Limited | Yes | -| Requests / 15-min window (application auth) | 15 | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request GET - --url https://api.x.com/1.1/account_activity/webhooks.json - --header 'authorization: Bearer TOKEN' -``` -### Example Response[](#example-response "Permalink to this headline") - -_HTTP 200 OK_ -```json - [ - { - "id": "1234567890", - "url": "https://your_domain.com/webhook/twitter/0", - "valid": true, - "created_at": "2016-06-02T23:54:02Z" - } - { - "id": "2468013579", - "url": "https://your_domain2.com/webhook/twitter/0", - "valid": true, - "created_at": "2016-06-04T22:31:29Z" - } - ] -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 99 | You don’t have access to this resource. | - -#### PUT account\_activity/webhooks/:webhook\_id[](#put-account-activity-webhooks-webhook-id "Permalink to this headline") -Triggers the challenge response check (CRC) for the given webhook's URL. If the check is successful, returns 204 and reenables the webhook by setting its status to `valid`. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (user context - all consumer and access tokens) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 15 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") -```json - $ curl --request PUT - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json - --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"' -``` -### Response[](#response "Permalink to this headline") - -_HTTP 204 OK_ -``` - { } -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 34 | Webhook does not exist or is associated with a different X application. | -| 214 | Webhook URL does not meet the requirements. | -| 214 | Webhook URL does not meet the requirements. Invalid CRC token or json response format. | -| 214 | High latency on CRC GET request. Your webhook should respond in less than 3 seconds. | -| 214 | Non-200 response code during CRC GET request (i.e. 404, 500, etc). | - -#### POST account\_activity/webhooks/:webhook\_id/subscriptions/all[](#post-account-activity-webhooks-webhook-id-subscriptions-all "Permalink to this headline") - -Subscribes the provided application to all events for the provided user context for all message types. After activation, all events for the requesting user will be sent to the application’s webhook via POST request. - -Subscriptions are currently limited based on your account configuration. If you have a need to add more subscriptions, please contact your account manager. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribing user's access token) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 500 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request POST - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json - --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"' -``` -### Example Response - Success[](#example-response-success "Permalink to this headline") - -_HTTP 204 NO CONTENT_ -``` - {} -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 34 | Webhook does not exist or is associated with a different X application. | -| 348 | Client application is not permitted to access this user's webhook subscriptions. | - -#### GET account_activity/subscriptions/count[](#get-account-activity-subscriptions-count "Permalink to this headline") - -Returns the count of subscriptions that are currently active on your account. Note that the /count endpoint requires application-only OAuth, so that you should make requests using a bearer token instead of user context. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/subscriptions/count.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | HTTP response code | -| Requires Authentication | Yes (application only - bearer token) | -| Rate Limited | Yes | -| Requests / 15-min window (application auth) | 15 | - -### HTTP Response Codes[](#http-response-codes "Permalink to this headline") - -| | | -| :--- | :--- | -| Code | Message | -| 200 | Success. A count of subscriptions for the requested webhook will be returned. | -| 401 | Your application does not have permission to view subscriptions for the specified webhook. | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request GET - --url https://api.x.com/1.1/account_activity/subscriptions/count.json - --header 'authorization: Bearer TOKEN' -``` -### Example Response - Success[](#example-response-success "Permalink to this headline") - -_HTTP 200_ -```bash - { - "account_name":"my-account", - "subscriptions_count_all":"1", - "subscriptions_count_direct_messages":"0", - "provisioned_count":"50" - } -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 32 | Could not authenticate you. | - -_HTTP 401_ -```abash - { - "errors": [ - { - "code": 32, - "message": "Could not authenticate you." - } - ] - } -``` -#### GET account\_activity/webhooks/:webhook\_id/subscriptions/all[](#get-account-activity-webhooks-webhook-id-subscriptions-all "Permalink to this headline") - -Provides a way to determine if a webhook configuration is subscribed to the provided user’s events. If the provided user context has an active subscription with provided application, returns 204 OK. If the response code is not 204, then the user does not have an active subscription. See HTTP Response code and error messages below for details. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribing user's access token) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 500 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") - - $ curl --request GET - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json - --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"' - -### Example Response - Success[](#example-response-success "Permalink to this headline") - -_HTTP 204 NO CONTENT_ -``` - { } -``` -#### GET account\_activity/webhooks/:webhook\_id/subscriptions/all/list[](#get-account-activity-webhooks-webhook-id-subscriptions-all-list "Permalink to this headline") - -Returns a list of the current All Activity type subscriptions for the specified webhook. Note that the /list endpoint requires application-only OAuth, so requests should be made using a bearer token instead of user context. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all/list.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | HTTP response code | -| Requires Authentication | Yes (application only - bearer token) | -| Rate Limited | Yes | -| Requests / 15-min window (application auth) | 50 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### HTTP Response Codes[](#http-response-codes "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 200 | Success. A list of subscriptions for the requested webhook will be returned. | -| 401 | Your application does not have permission to view subscriptions for the specified webhook. | - -### Example Request[](#example-request "Permalink to this headline") - - $ curl --request GET - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all/list.json - --header 'authorization: Bearer TOKEN' - -### Example Response - Success[](#example-response-success "Permalink to this headline") - -_HTTP 200_ -```bash - { - "webhook_id": "1234567890", - "webhook_url": "https://your_domain.com/webhook/twitter/0", - "application_id": "11231812", - "subscriptions": [{ - "user_id": "20212306" - }] - } -``` -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 32 | Could not authenticate you. | - -_HTTP 401_ -```bash - { - "errors": [ - { - "code": 32, - "message": "Could not authenticate you." - } - ] - } -``` -#### DELETE account\_activity/webhooks/:webhook\_id[](#delete-account-activity-webhooks-webhook-id "Permalink to this headline") - -Removes the webhook from the provided application's configuration. The webhook ID can be accessed by making a call to GET /1.1/account_activity/webhooks. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (user context - all consumer and access tokens) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 15 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request DELETE - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json - --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"' -``` -### Response[](#response "Permalink to this headline") - -_HTTP 204 OK_ -``` - { } -``` -#### DELETE account\_activity/webhooks/:webhook\_id/subscriptions/all (DEPRECATED)[](#delete-account-activity-webhooks-webhook-id-subscriptions-all-deprecated- "Permalink to this headline") - -Deactivates subscription(s) for the provided user context and application. After deactivation, all events for the requesting user will no longer be sent to the webhook URL. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribed user's access token) | -| Rate Limited | Yes | -| Requests / 15-min window (user auth) | 500 | - -### Parameters[](#parameters "Permalink to this headline") - -| | | -| :--- | :--- | -| webhook_id (required) | Webhook ID. Defined in resource path. | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request DELETE - --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json - --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBED_USER'S_ACCESS_TOKEN", oauth_version="1.0"' -``` - Example Request -``` - { } -``` -#### DELETE /account\_activity/webhooks/:webhook\_id/subscriptions/:user_id/all.json[](#delete-account-activity-webhooks-webhook-id-subscriptions-user-id-all-json "Permalink to this headline") - -Deactivates subscription for the specified webhook and user id. After deactivation, all events for the requesting user will no longer be sent to the webhook URL. Note, that this endpoint requires application-only OAuth, so requests should be made using a bearer token instead of user context. - -### Resource URL[](#resource-url "Permalink to this headline") - -`https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json` - -### Resource Information[](#resource-information "Permalink to this headline") - -| | | -| :--- | :--- | -| Response Format | JSON | -| Requires Authentication | Yes (application only - bearer token) | -| Rate Limited | Yes | -| Requests / 15-min window | 500 | - -### Example Request[](#example-request "Permalink to this headline") -```bash - $ curl --request DELETE - --url https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json - --header 'authorization: Bearer TOKEN' -``` - -### Response[](#response "Permalink to this headline") - -_HTTP 204 NO CONTENT_ - -### Error Messages[](#error-messages "Permalink to this headline") - -| Code | Message | -| :--- | :--- | -| 404 | Sorry, that page does not exist. - This often occurs when the specified user id is not actually subscribed. | - - -### Replay API - -**POST /1.1/account\_activity/replay/webhooks/:webhook\_id/subscriptions/all.json [¶](#post-1-1-account-activity-replay-webhooks-webhook-id-subscriptions-all-json- "Permalink to this headline")** - -Submits a request to retrieve activities from up to the past five days from all subscriptions present during the date and time windows specified in the request. If your webhook has active user subscriptions, you will concurrently receive those events as well. Note: We do perform a CRC before delivering replay events. - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | /1.1/account\_activity/replay/webhooks/:webhook\_id/subscriptions/all.json?from\_date=yyyymmddhhmm&to\_date=yyyymmddhhmm | -| **Response Format** | JSON | -| **Requires Authentication** | Yes (application only - bearer token) | -| **Rate Limit** | 5 requests per 15 minutes. There is currently no maximum on the number of replay jobs that can requested. | -| **from_date** | The oldest (starting) UTC timestamp from which the events will be provided, must be in 'yyyymmddhhmm' format. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute). Valid times must be within the last 5 days, UTC time, and no more recent than 31 minutes before the current point in time. It's recommended that the from\_date and to\_date should be within ~2 hours. | -| **to_date** | The latest (ending) UTC timestamp to which the event will be provided, must be in 'yyyymmddhhmm' format. Timestamp is in minute granularity and is exclusive (i.e. 12:30 does not include the 30th minute of the hour). Valid times must be within the last 5 days, UTC time, and no more recent than 10 minutes before the current point in time. | - - - -#### Responses - -The following responses may be returned by the API. Most error codes are returned with a string including additional details in the body. For non-200 responses, you should resolve the error and try again. - -| Status | Text | Error Code | Description | Message | -| :--- | :--- | :--- | :--- | :--- | -| 202 | Accepted | N/A | The request was successful and the activities will be sent. | N/A | -| 400 | Bad Request | 214 | Webhook has been marked as invalid. | Webhook is marked invalid and requires a CRC check. | -| 400 | Bad Request | 357 | Query parameter is missing. | : queryParam is required. | -| 400 | Bad Request | 358 | Route or query parameter is malformed. | Unable to parse parameter. | -| 400 | Bad Request | 360 | Route parameter is negative. | webhook_id: \[\] is not greater than or equal to 0. | -| 400 | Bad Request | 368 | from\_date or to\_date is not in the past. | : \[<field_value>\] is not in the past. | -| 400 | Bad Request | 356 | from\_date must be before to\_date. | from\_date must be before to\_date. | -| 400 | Bad Request | 356 | from_date must be within the past 5 days. | from_date must be within the past 5 days. | -| 401 | Unauthorized | 32 | HTTP authentication failed due to 3-legged auth provided. | Invalid authentication method. Please use application-only authentication. | -| 401 | Unauthorized | 61 | Client is not permitted to request this method. | Client is not permitted to request this method. | -| 403 | Forbidden | 200 | Client does not have an enterprise account with Replay enabled. | Account Activity API enterprise account with replay is required. Please confirm you have an enterprise account and replay is enabled. | -| 404 | Not Found | 34 | Non-existing webhook\_id; webhook\_id-application_id mismatch. | Webhook does not exist or is associated with a different X application. | -| 409 | Conflict | 355 | There is a request in flight and it will need to finish processing before making another. | A replay job is already in progress for this webhook. | -| 429 | Too Many Requests | 88 | Rate limited (hit limit of the number of requests per time period) | Too many requests. Please back off your API request rate. | -| 500 | Internal Server Error | 0 | Internal server error. | Internal server error. | -| 503 | Service Unavailable | 67 | One or more dependent services at X is unavailable. | X server error. Retry using an exponential backoff pattern. | - - - -#### "Job completed successfully” message - -Once your job successfully completes, Account Activity Replay API will deliver the following job completion event. Once you receive this event, the job has finished running and another can be submitted. -```json -{ - "replay\_job\_status": { - "webhook_id": "1234577122340233217", - "job_state": "Complete", - "job\_state\_description": "Job completed successfully" - "job_id": "1095098195724558337" - } -} -``` -#### "Job failed to complete" message - -In the event your job does not complete successfully, we will return the following message encouraging you to retry your Replay job. Once you receive this event, the job has finished running and another can be submitted. -```json -{ - "replay\_job\_status": { - "webhook_id": "123451374207332352", - "job_state": "Incomplete", - "job\_state\_description": "Job failed to deliver all events, please retry your replay job", - "job_id": "1093226942650736640" - } -} -``` -#### Example curl request -```bash - curl --request POST --url 'https://api.x.com/1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm' - --header 'authorization: Bearer TOKEN' -``` -#### Example response - -HTTP 202 -```bash -{ - "job_id": "1234567890", - "created_at": "2016-06-02T23:54:02Z" -} -``` +By the end of this video, you will learn abo \ No newline at end of file diff --git a/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments.mdx b/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments.mdx index 2f507d2ba..e4191fa6a 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments.mdx @@ -1,7 +1,8 @@ --- title: "Data enrichments: Enterprise" keywords: ["data enrichments", "enterprise enrichments", "GNIP enrichments", "data enrichment", "enriched data", "enterprise data enrichment"] ---- + +description: `Enterprise` Enterprise enrichments are additive metadata included in the response payload of some of the data APIs. They are available in paid subscrip...--- ## Introduction @@ -256,24 +257,4 @@ The Historical PowerTrack, Search, and PowerTrack APIs supports filtering based "region": "Alabama", "sub_region": "Jefferson County", "full_name": "Birmingham, Alabama, United States", - "geo": { - "coordinates": \[ - -86.80249, - 33.52066 - \], - "type": "point" - } - } - \] - } - } -} -``` -#### Limitations - -* The Profile Geo enrichment attempts to determine the best choice for the geographic place described in the profile location string. The result may not be accurate in all cases due to factors such as multiple places with similar names or ambiguous names. -* If a value is not provided in a user’s profile location field (actor.location), we will not attempt to make a classification. -* Precision Level: If a Profile Geo Enrichment can only be determined with confidence at the country or region level, lower-level geographies such as subRegion and locality will be omitted from the payload. -* The Profile Geo enrichment provides lat/long coordinates (a single point) that corresponds to the Precision Level of the enrichment’s results. These coordinates represent the geographic center of the enrichment location results. For example, if the Precision Level is at the Country level, then those coordinates are set to the geographic center of that Country. -* The PowerTrack operators provided for address properties (locality/region/country/country code) are intentionally granular to allow for many rule combinations. When attempting to target a specific location that shares a name with another location, consider combining address rules. For instance, the following would avoid matches for “San Francisco, Philippines”: profile\_locality:”San Francisco” profile\_region:California When building rules that target individual Profile Geo fields, keep in mind that each increased level of granularity will limit the results you see. In some cases when attempting to look at data from a city, you may wish to only rely on a region rule where the region offers significant overlap with the city, e.g. the city of Zurich, Switzerland can be effectively targeted along with surrounding areas with profile_region:”Zurich”. -* Use with Native Geo Posts: The Profile Geo enrichment provides an alternative type of geography for a Post, different from the native geo value in the payload. These two types of geography can be combined together to capture all of the possible posts related to a given area (based on available geodata), though they are not conceptually equivalent. + "geo" \ No newline at end of file diff --git a/x-api/enterprise-gnip-2.0/fundamentals/decahose-api.mdx b/x-api/enterprise-gnip-2.0/fundamentals/decahose-api.mdx index 7a2690c5b..5f3d23e0e 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/decahose-api.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/decahose-api.mdx @@ -1,7 +1,8 @@ --- title: Decahose API keywords: ["Decahose", "10% stream", "decahose API", "enterprise decahose", "10% sampled stream", "enterprise streaming"] ---- + +description: [Enterprise](https://developer.--- This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the ["Edit Posts" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets).  @@ -239,157 +240,4 @@ The number of streams, and their unique labels, is configurable by your account **Redundant Connections** -A redundant connection simply allows you to establish more than one simultaneous connection to the data stream. This provides redundancy by allowing you to connect to the same stream with two separate consumers, receiving the same data through both connections. Thus, your app has a hot failover for various situations, e.g. where one stream is disconnected or where your app’s primary server fails. - -The number of connections allowed for any given stream is configurable by your account representative. To use a redundant stream, simply connect to the same URL used for your primary connection. The data for your stream will be sent through both connections, with both stream connections represented on the stream dashboard. - -Note that for billing purposes, we deduplicate the activity counts you receive through multiple connections such that you are only billed for each unique activity once. Given the Decahose has two partitions, here's an example of how the connection count works below: - -Connect to decahose partition=1 -Connect to decahose partition=1 -Connect to decahose partition=2 - -The above situation yields a total of three connections – two connections to partition=1 and one connection to partition=2. Normally, you would want the same number of connections to each partition, so this example highlights a situation where the redundant connection to partition=2 has dropped and you want to further invstigate. - -**Recovery** - -#### Overview  - -Recovery is a data recovery tool (not to be used for primary data collection) that provides streaming access to a rolling 5-day window of recent X historical data. It should be utilized to recover data in scenarios where your consuming application misses data in the realtime stream, whether due to disconnecting for a short period, or for any other scenario where you fail to ingest realtime data for a period of time. - -#### Using Recovery  - -With the Recovery stream, your app can make requests to it that operate in the same manner as requests to the realtime streams. However, your app must specify parameters in the URL that indicate the time window you are requesting. In other words, a Recovery request asks the API for "Posts from time A to time B." These Posts are then delivered through your streaming connection in a manner that mimics the realtime stream, but at a slightly slower-than-realtime rate. See below for example: - - -"https://stream-data-api.x.com/stream/powertrack/accounts/someAccountName/publishers/twitter/powertrack.json?startTime=2023-07-05T17:09:12.070Z" - -Posts are delivered beginning with the first (oldest) minute of the specified time period, continuing chronologically until the final minute is delivered. At that point, aRecovery Request Completed message is sent through the connection, and the connection is then closed by the server. If your request begins at a time of day where little or no matching results occurred, there will likely be some period of time before the first results are delivered – data will be delivered when Recovery encounters matches in the portion of the archive being processed at that time. When no results are available to deliver, the stream will continue sending carriage-return, or "heartbeats", through the connection to prevent you from timing out. - -Recovery is intended as a tool for easily recovering data missed due to short disconnects, not for very long time periods like an entire day. If the need to recover data for long periods arises, we recommend breaking longer requests into shorter time windows (e.g. two hours) to reduce the possibility of being disconnected mid-request due to internet volatility or other reasons, and to provide more visibility into the progress of long requests. - -#### Data Availability - -You can use the Recovery feature to recover missed data within the last 24 hours if you are unable to reconnect with the 5 minute backfill window. - -The streaming recovery feature allows you to have an extended backfill window of 24 hours. Recovery enables you to ‘recover’ the time period of missed data. A recovery stream is started when you make a connection request using 'start\_time' and 'end\_time' request parameters. Once connected, Recovery will re-stream the time period indicated, then disconnect.   - -You will be able to make 2 concurrent requests to recovery at the same time, i.e. “two recovery jobs”. Recovery works technically in the same way as backfill, except a start and end time is defined. A recovery period is for a single time range. - -#### Backfill - -To request backfill, you need to add a backfillMinutes=N parameter to your connection request, where N is the number of minutes (1-5, whole numbers only) to backfill when the connection is made. For example, if you disconnect for 90 seconds, you should add backfillMinutes=2 to your connection request. Since this request will provide backfill for 2 minutes, including for the 30-second period before you disconnected, your _consumer app must be tolerant of duplicate data_. - -An example Decahose connection request URL, requesting a 5 minute backfill to partition 1, looks like: - -https://gnip-stream.x.com/stream/sample10/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition=1&backfillMinutes=5 - -**NOTES:** - -* You do have the option to always use ‘backfillMinutes=5’ when you connect, then handling any duplicate data that is provided. - -* If you are disconnected for more than five minutes, you can recover data using Recovery. - - - -**Recovering from Disconnect** - -Restarting and recovering from a disconnect involves several steps: - -* Determining length of disconnect time period. - * 5 minutes or less? - * If you have Backfill enabled for stream, prepare connection request with appropriate ‘backfillMinutes’ parameter. - * More than 5 minutes? - * If you have a Recovery stream, make a Recovery request for the disconnected time period (ideally with your current realtime rule set, using the Rules API if necessary). -* Request a new connection. - -When you experience disconnects or downtime, here are strategies to mitigate and recover in this scenario: - -1. **Implement backfill** - Backfill lets you reconnect from a point prior to disconnecting from a stream connection, and covers disconnects of up to 5 minutes. It is implemented by including a parameter in the connection request. - -2. **Consume a redundant stream from another location** - If the redundant stream can be streamed into the same live environment, deduplicating data, you will eliminate the need for recovery unless BOTH the normal stream and redundant stream experience simultaneous downtime or disconnects. If the redundant stream cannot be streamed live into the production environment, it can be written into a separate “emergency” data store. Then, in the event of disconnects or downtime on the primary stream connection, your system will have data on hand to fill in your primary database for the period of time where data is missing - -3. **Implement Recovery** - Where disconnects or downtime affect both the primary stream and redundant stream, use the Decahose Recovery to recover any data missed. The API provides a rolling window covering 5 days of the archive, and would be best utilized by requesting no more than an hour of that window at a time, and streaming it in. This is done in parallel to the realtime stream. Note that we do not have solutions for recovering Decahose data from beyond the 5 day window provided by Recovery, so it is important for you to utilize a redundant stream to ensure you have a complete copy of data on your side in the case of significant downtime on your side. - - -When you detect abnormal stored data volumes-  -Potential ways you can detect missing data where no disconnects or downtime occurred… - -1. Count inbound Posts - Your system should count the raw number of Posts you receive at the very beginning of your ingestion app, and then provide a way to compare those numbers to the number of Posts that reaches your final data store. Any differences can be monitored, and alert your team to issues causing data to be dropped after it is received. - -2. Analyze for abnormal stored volumes - You may also want to analyze the volumes of stored data in your final database to look for abnormal drops. This can indicate issues as well, although there will likely be circumstances in which drops in volume are normal (e.g. if the X platform is unavailable and people are not able to create Posts for some period of time). - -## API Reference - -### Decahose stream - -Jump to on this page - -[Methods](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#methods) - -[Authentication](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#authentication) - -[GET /\{stream-type}/:stream](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#get-stream-type-stream) - -[Replay API](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#replay-api) - -#### Methods - -| Method | Description | -| :--- | :--- | -| [GET /\{stream-type}/:stream](#Stream) | Connect to the data stream | - -#### Authentication[](#authentication- "Permalink to this headline") - - -All requests to the Volume Stream APIs must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. So confirm that your client is adding the "Authentication: Basic" HTTP header (with encoded credentials over HTTPS) to all API requests. - -#### GET \{stream-type}\:stream - -Establishes a persistent connection to the Firehose stream, through which the realtime data will be delivered. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **Connection Type** | Keep-Alive

This should be specified in the header of the request. | -| **URL** | Found on the stream's API Help page of your dashboard, using the following structure:

Decahose:

[https://gnip-stream.x.com/stream/sample10/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition=1](https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1) | -| **Partition (required)** | `partition=\{#}` \- Partitioning is now required in order to consume the full stream. You will need to connect to the stream with the partition parameter specified. Below is the number of partitions per stream:

* Decahose: 2 partitions | -| **Compression** | Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following:

Accept-Encoding: gzip | -| **Character Encoding** | UTF-8 | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | 10 requests per 60 seconds. | -| **Backfill Parameter** | If you have purchased a stream with Backfill enabled, you'll need to add the "backfillMinutes" parameter into GET request to enable it. | -| **Read Timeout** | Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds. | -| **Support for Tweet edits** | All Tweet objects will include Tweet edit metadata describing the Tweet's edit history. See the ["Edit Tweets" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) for more details. | - -#### Responses - -The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | Success | The connection was successfully opened, and new activities will be sent through as they arrive. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 406 | Not Acceptable | Generally, this occurs where your client fails to properly include the headers to accept gzip encoding from the stream, but can occur in other circumstances as well.

Will contain a JSON message similar to "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end." | -| 429 | Rate Limited | Your app has exceeded the limit on connection requests. | -| 503 | Service Unavailable | Twitter server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support or emergency if unable to connect after 10 minutes. | - -#### Example curl Request - -The following example request is accomplished using cURL on the command line. However, note that these requests may also be sent with the programming language of your choice: - -``` -curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/firehose/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition={#}" -``` -#### Replay API - -The Replay API is an important complement to realtime Volume streams. Replay is a data recovery tool that provides streaming access to a rolling window of recent X historical data. - - +A redundant connection simply allows you to establish more than one simultaneous connection to the data stream. This provides redundancy by allowing you to connect to the same stream with two separate consumers, receiving the same data through both connections. Thus, your app has a hot failover for various situations, e.g. where one stream is disconnecte \ No newline at end of file diff --git a/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets.mdx b/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets.mdx index 3fb6e654b..cdcd8e2d3 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets.mdx @@ -1,7 +1,8 @@ --- title: Edit Tweets keywords: ["edit tweets enterprise", "enterprise edit tweets", "edit posts enterprise", "tweet edits enterprise", "edit metadata enterprise"] ---- + +description: Enterprise endpoints have been updated to provide edited Post metadata. The _Edit Posts _feature was first introduced for testing among X employees on S...--- Enterprise endpoints have been updated to provide edited Post metadata. The _Edit Posts _feature was first introduced for testing among X employees on September 1, 2022. Starting on that date, eligible Posts were editable for 30 minutes and up to 5 times. _All objects for Posts created since September 29, 2022_ include Post edit metadata, even if the Post was never edited. Each time a Posts is edited, a new Post ID is created. A Post's edit history can be described by chaining these IDs together, starting with the original ID. Additionally, if any Post in the edit chain is deleted, all Posts in that chain are deleted as well.  These metadata details are included automatically. No request parameters are needed to include available edit history as part of the Post object.  diff --git a/x-api/enterprise-gnip-2.0/fundamentals/engagement-api.mdx b/x-api/enterprise-gnip-2.0/fundamentals/engagement-api.mdx index 8687919c0..e8f454065 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/engagement-api.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/engagement-api.mdx @@ -1,7 +1,8 @@ --- title: Engagement API keywords: ["Engagement API", "enterprise Engagement API", "engagement metrics", "engagement data", "enterprise engagement", "GNIP engagement"] ---- + +description: [`Enterprise`](https://developer.--- ## Overview [`Enterprise`](https://developer.x.com/en/products/x-api/enterprise) @@ -132,685 +133,4 @@ Now that we’ve explored the ‘whys’ of the Engagement API, let’s start di The Engagement API is a simple RESTful API that receives requests encoded in JSON and responds with engagement metrics encoded in JSON. Requests consist three main parts (follow links for more documentation): * Array of **_Post IDs_**. -* Array specifying the [metric types](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#EngagementTypes) of interest. Types include things such as ‘impressions’, ‘retweets’, ‘hashtag\_clicks’, and ‘user\_follows’. -* [Engagement groupings](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings), which is a JSON structure indicating how you want the engagement data arranged in the API response. - - -In many situations, the Engagement Types and Groupings will remains relatively constant from request to request, with only the Post IDs being updated. - -The Engagement API provides [three endpoints](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#RequestEndpoints): - -* **Totals** \- Provides grand totals of engagements for Posts. Some metrics are available for all Posts, while others are only available for the past 90 days. -* **28 hour** \- Provides time-series engagement metrics from the last 28 hours. -* **Historical** \- Provides time-series engagement metrics for up to four consecutive weeks for Posts posted since September 1, 2014. - - -The **/totals** endpoint supports requesting metrics for up to **250 Posts per request**. The **/28hour** and **/historical** endpoints support **25 per request**. - -After discussing getting access to the Engagement API, we’ll walk through making an API request, provide an OAuth overview, and provide links to other technical resources. - -##### **Getting API access** - -If you are reading this document, you have most likely already obtained access to the Engagement API. If not, please reach out to your Enterprise account manager, or apply for Enterprise access [here](/x-api/enterprise-gnip-2.0/enterprise-gnip). - -The first step is creating a [X app](/resources/fundamentals/developer-apps) using an approved developer account via the [Developer Console](/resources/fundamentals/developer-portal).  Your account manager will need the numeric App ID associated with this application to provide access. If you need to apply for a developer account, you can do so [here](/resources/fundamentals/developer-apps). - -##### **Making a request** - -The good news is that making requests to the Engagement API is simple. For our request, we’ll ask it for total Retweets, Quote Tweets, Favorites, and replies, for the following two [@XDevelopers](https://x.com/XDevelopers) Posts: - -> 1/ Today we’re sharing our vision for the future of the X API platform![https://t.co/XweGngmxlP](https://t.co/XweGngmxlP) -> -> — Twitter Dev (@TwitterDev) [April 6, 2017](https://x.com/TwitterDev/status/850006245121695744) - -> Don’t miss the Posts about your Post. -> -> Now on iOS, you can see Retweets with comments all in one place. [pic.x.com/oanjZfzC6y](https://t.co/oanjZfzC6y) -> -> — X (@X) [May 12, 2020](https://x.com/status/1260294888811347969?ref_src=twsrc%5Etfw) - -The first step is constructing the API request in JSON, consisting of these two Post IDs placed in an array, an array of engagement types of interest, and a custom-named “groupings” JSON object that indicates how we want the metrics arranged in the response. Here is what our request looks like: - -```json -{ - "tweet_ids": [ - 1260294888811347969, 850006245121695744 - ], - "engagement_types": [ - "retweets", "quote_tweets", "favorites", "replies" - ], - "groupings": { - "engagement-types-by-id": { - "group_by": [ - "Tweet.id", "engagement.type" - ] - } - } -} -``` - -To retrieve these total metrics, we POST this JSON request to the https://data-api.x.com/insights/engagement/totals endpoint. - -We’ll include the following headers to indicate that our request is encoded in JSON, and that it is Gzipped (request bodies can get big): - -* Content-Type: application/json -* Accept-Encoding: gzip -   - -When making requests we authenticate using OAuth, which we’ll discuss more in the next section. - -The API returns the following payload: - -```json -{ - "grouping name": { - "1260294888811347969": { - "favorites": "17111", - "quote_tweets": "3254", - "replies": "1828", - "retweets": "5218" - }, - "850006245121695744": { - "favorites": "492", - "quote_tweets": "66", - "replies": "42", - "retweets": "324" - } - } -} -``` - - -Note that the response has our requested metrics in the structure described by the “groupings” definitions, with metrics listed by Post ID first, then by engagement type on the next level. - -That was pretty simple. If you are new to authenticating with OAuth, check out the next section. - - -#### Authenticating with OAuth - -OAuth is an authentication standard that is very common in the technology industry.  If you are already using OAuth (perhaps with other X APIs) then you are likely using a language-specific OAuth package that abstracts away all the gnarly details. If you are new to OAuth, please visit our [Oauth with the X API](/resources/fundamentals/authentication) page or head directly to the [https://oauth.net](https://oauth.net/) to learn more. Then we recommend that you find an OAuth package for your integration language of choice and start there. With these packages, the path to authenticating typically means configuring your keys and tokens, creating some sort of HTTP object, then making requests with that object. - -For example, in the Ruby world, the following pseudo-code represents a recipe to build an OAuth-enabled app using the Ruby gem ‘oauth’ and making a POST request:   - -```js -require 'oauth' - -#Assemble JSON request (as above). -request = make_json_request() - -#Build an app consumer object with my app consumer key and secret. -consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => ‘https://data-api.x.com’}) -#Build a user token with tokens provided by account providing permission. If making app-only #request (checking Tweets that do not require permission with /totals endpoint), this step can be #skipped. -token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']} - -#Create oauth-enabled app object. -app = OAuth::AccessToken.from_hash(consumer, token) -#Make POST request. -result = app.post(“/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"}) -``` - -The Engagement API supports both application-only and user-context authentication. If you are collecting engagement metrics for unowned public Posts with the /totals endpoint then no user permission is required and you can use application-only authentication. In this case, you’ll use only your app key and secret to authenticate. - -OAuth also allows an app to make an API request “on behalf of another user”, using tokens that relate to the user. If you are generating Engagement metrics for owned Posts, ie Posts that were published by a user whom you have user tokens for, you will be making requests with a user context, meaning authenticating with both your app keys and user-specific access tokens. These user access tokens are typically supplied with the '[Sign-in with X](/resources/fundamentals/authentication#log-in-with-x)' process or acquired directly from the user (please note that you must use [twurl](https://github.com/xdevplatform/xurl) if you acquire the tokens directly from the user). Once the user provides their tokens, they do not expire and can be used with the Engagement API to make requests on their behalf,  as long as the user doesn't reset their tokens or change their password, in which case they will have to provide you the new tokens. - -You can review which metrics require which authentication via [this table](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings). -  - -### Selecting an Engagement API Endpoint - -The Engagement API provides three distinct endpoints: - -* **[Totals](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement)** - provides grand totals of select metrics from owned 'owned' or 'unowned' Posts. Some metrics are available for all Posts, while others are only available for Posts published in the last 90 days. Supports 250 Posts per request. -* **[28 hour](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement)** - provides time-series Engagement metrics for ‘owned’ Posts from the last 28 hours. Supports 25 Posts per request. -* **[Historical](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement-historical)** \- provides time-series Engagement metrics for up to four consecutive weeks for ‘owned’ Posts posted since September 1, 2014. Supports 25 Posts per request. -   - -Each endpoint has its own unique characteristics. Whether you are planning to use all three, or are trying to decide which one best matches your use case, it’s important to understand the differences between them. - -Below we introduce some key concepts, further explore the three endpoints, and then present example use cases that map generally to a specific endpoint. Our hope is that this information will help you more efficiently integrate all three, or help you decide which single endpoint best fits your mission. -  - -#### Key concepts - -There are several key concepts that help illustrate the different features of, and data provided by, the three Engagement API endpoints. -  - -##### Impressions and engagement metrics - -Impressions represent the number of times that a given Post has been viewed on the X platform in an organic context. Impressions generated from Posts that are seen in a Promoted or Paid context are not included. Before the Engagement API, Post impressions represented only a measure of potential views. It was based on counting followers of the author’s account and those of any account Retweeting the content. It did not take into account the common situation when a given user does not actually see the Post. - -The impression metrics generated by the Engagement API is an actual measure of the number of times a Post has been rendered for display. If a follower of your account misses your Post, it does not count as an impression. - -The Engagement API provides metrics on 14 unique engagement [metric types](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#available-metrics), each representing a distinct action a user can take when presented a Post. These include Retweeting, Liking, Replying, clicking on entities like #hashtags, links and media, following the author, and viewing the author’s profile. All of these individual actions are rolled up into a single Engagements metric. - - -##### Owned and unowned X content - -The Engagement makes a clear distinction between owned and unowned Posts. Owned Posts are Posts that are posted from your account, or Posts that you have obtained permission to request Engagement data for. As with other X APIs, you obtain permission by having other X users/accounts share access tokens that enable you to make API requests on their behalf. A common way to obtain these tokens is with the [‘Sign in with X’ process](/resources/fundamentals/authentication#log-in-with-x). - -The /totals endpoint provides engagement data for both owned and unowned Posts. For unowned Posts, you can request engagement metrics that are publicly available in a Post display: Favorite, Retweet, and Reply. For these metrics, what the Engagement API brings to the table is the ability to retrieve these metrics at scale in an automated way. For owned Posts, the /totals endpoint also provides Impression and (total) Engagement metrics. - -The /28hr and /historical endpoints provide metrics for owned Posts only, meaning that you have to pass along user context when making the request to these endpoints. - - -##### Total and time-series engagement Data - -The /totals endpoint provides, as its name implies, only grand totals for its engagement types. Its numbers represent the up-to-date totals since the Post was posted. If a Post was just posted and you repeatedly request its metrics, these totals will commonly change with each request. - -The /28hr and /historical endpoints can provide both grand totals and time-series data. When requesting time-series data, the engagement metrics can be rolled up into daily or hourly data.    - -See our documentation on [engagement groupings](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings) for how to request time-series data with the /28hr and /historical endpoints. - - -#### Endpoints and example use cases - -Given the characteristics and differences discussed above, each individual endpoint generally maps to different types of use cases. To help you decide which endpoint best serves your particular use case, below are some example user statements and the endpoint that best satisfies it. - -##### **/totals** - -* I only need access to some metric types (Impressions, Engagements, Favorites, Retweets, Quote Tweets, Replies, and Video Views). -* I need access to basic engagement data for any Post, not just owned Posts. -* I want to compare performance against a competitor. -* I want to track basic engagement stats for a hashtag or campaign that includes Posts that I don’t own. -* I don’t need data broken out by day or hour, I just need the current total when I make a request. -* I need a single metric to show in a report or dashboard and don’t want to store any data. -* I want to show data at page load time, and just need to make a request and get a response. -* I need access to get data for hundreds of thousands or millions of Posts per day. -   - -##### **/28hr** - -* I need access to all 17 metric types. -* I want to show data for very recent Posts posted in last 28 hours. -* I have a job that runs once a day to get data that I care about and only need to get data for the last day. -* I need to have metrics broken out by day or hour. -* I want to show time-series breakouts of activity by hour in a dashboard. -* I need high access for hundreds of thousands to Posts per day -* I have storage capabilities and can refresh data once per day and keep a running tally. -   - -##### **/historical** - -* I need access to all 17 metric types. -* I need to get historical data for Posts created all the way back to September 2014. -* I want to show detailed historical analysis that compares campaigns. -* I need to have metrics broken out by day or hour. -* I don’t need high access to the Engagement API and only need to get data for a few hundred or thousand Posts per day. - - -### Engagement API key characteristics - -* **RESTful API** serving JSON data, supporting POST requests with JSON data bodies. -* **Types of Requests:** Client apps may make the following types of requests: - * **Total engagements** \-- HTTP POST request to /totals endpoint - * **Last 28-hour engagements** \-- HTTP POST request to /28hr endpoint - * **Historical engagements** \-- HTTP POST request to /historical endpoint -* **OAuth authentication:** - * [OAuth 1.0 User Context](/resources/fundamentals/authentication): All available metrics are available for Posts that are owned by a user that has authorized your App using [3-legged OAuth](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens). You must use that user's Access Tokens when making your request.[](/resources/fundamentals/authentication) - * [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#oauth-2-0): Select metrics (Retweets, Quote Tweets, Replies, Favorites, and Video Views) are available for any public Post.  -* **Request metadata and structure**: Request data is a JSON object consisting of a Post ID array, an array of engagement types, and an engagement grouping structure. -* **Posts per request:** - * /totals endpoint: 250 Post IDs - * /28hr endpoint: 25 Post IDs - * /historical endpoint: 25 Post IDs -* **Engagement metrics availability:** - * **/totals** -- Metric totals since when Post was posted. Impressions and Engagements are available for Posts published in the last 90 days, while Retweets, Quote Tweets, Replies, Favorites, and Video Views are available for all Posts. - * **/28hr** -- Last 28 hours from time of request. - * **/historical** -- Any 28-day period starting September 1, 2014. -* **Metric types**: Each request includes an array of [Metric Types](http://support.gnip.com/apis/engagement_api/overview.html#EngagementTypes). The availability of these depends on the endpoint and, if requesting from the /totals endpoint, on whether Posts are user-permissioned. - * /totals endpoint: - * All Posts: Favorites, Retweets, Quote Tweets, Replies, and Video Views - * Requires OAuth 1.0a User Context: Impressions, Engagements, Favorites, Replies, and Retweets - * /28hr and /historical endpoints (Requires OAuth 1.0a User Context with Post owner's Access Token): Impressions, Engagements, Favorites, Replies, Retweets, URL Clicks, Hashtag Clicks, Detail Click, Permalink Clicks, Media Clicks, App Install Attempts, App Opens, Post Emails, Video Views, and Media Views -* **Engagement groupings:** Each request includes an array of [Engagement Groupings](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#engagement-api-groupings). With these groupings you can customize how the returned metrics are organized. Up to three groupings can be included with each request. Metrics can be organized by the following values: - * All endpoints: Post ID, Engagement Type - * /28hr and /historical endpoints: These endpoints provide time-series if these additional groupings are specified: Engagement Day, Engagement Hour -* **Integration Expectations:** Your team will be responsible for the following. - * Creating and maintaining a client app that can send HTTP requests to the Engagement API that returns engagement metrics for Post ID included in request. -* **Limitations** -* Video views are only available for Posts that are 1800 days old or less. - - -### Authenticating with the Engagement API - - ->**Please note**:  -> ->X needs to enable access to the Engagement API for your developer App before you can start using the API. To this end, make sure to share the App ID that you intend to use for authentication purposes with your account manager or technical support team. - -There are two authentication methods available with the Engagement API: [OAuth 1.0a](/resources/fundamentals/authentication#oauth-1-0a-2) and [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only).  - -**OAuth 2.0 Bearer Token** (also referred to as “application-only”) allows you to access publicly available engagement metrics. This authentication method can be used to get total counts for Favorites (aka Likes), Retweets, Quote Tweets, Replies, and video views for any publicly available Posts when making requests to the [/totals endpoint](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement-totals).  - -**OAuth 1.0a** (also referred to as “user context”) allows you to make requests on behalf of a user and access private engagement metrics that belong to the user in question.  - -This authentication method is required for: - -* All requests sent to the [/28hr endpoint](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement-28hr) and [/historical endpoint](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement-historical) -* Accessing any of the following private metrics: Impressions, Engagements, Media Views, Media Engagements, URL Clicks, Hashtag Clicks, Detail Expands, Permalink Clicks, App Install Attempts, App Opens, Email Post, User Follows, and User Profile Clicks - -When sending a request with OAuth 1.0a, you need to include the Access Tokens (Access Token and Secret) of the user who owns the Post or protected resource of interest. If you do not provide the correct user Access Tokens when requesting protected user data, the Engagement API will return a `403 Forbidden` error. - -The Engagement API will not allow you to fetch engagement data for [protected Posts](https://help.x.com/en/safety-and-security/public-and-protected-tweets), even if you are authenticating on behalf of the user who owns these Posts. Attempting to do so will return a `400 Bad Request` error, with the message `"Tweet ID(s) are unavailable"`. - -If you are sending a request on behalf of your own X account (in other words, the account that owns the developer App), you can generate the required Access Tokens directly from within the [Developer Console](https://developer.x.com/en/portal/projects-and-apps), under the “Keys and tokens” tab for the developer App. - -If you are making a request on behalf of any other user, you will need to use the 3-legged OAuth flow to obtain the required Access Tokens. The following documentation contains more information on how to do this: [OAuth 1.0a: how to obtain a user’s access tokens](/resources/fundamentals/authentication#oauth-1-0a-2). - -For additional examples, including how to authenticate using OAuth 1.0a, check out[XDevelopers sample Python code for the Engagement API](https://github.com/xdevplatform/enterprise-scripts-python/tree/master/Engagement-API). - - -### Recent changes to the Engagement API - -The Engagement API delivers invaluable impression and engagement metrics that enable you to monitor the performance of your activity on X. In our continual effort to enable marketing decisions based on our data, we are excited to share recent changes to the Engagement API that provide greater consistency with metrics across all of X.   - -We recently deployed changes to modernize the Engagement API to use the same metrics aggregation methodology in use by the X analytics dashboard (analytics.x.com). We took a thoughtful approach to try and minimize breaking API changes when rolling out these new metrics and deployed the first set of changes on October 9, 2017. These changes improve consistency from all of the places you or your customers might monitor your performance on X. Please see the detailed outline of the changes below: - -| | | -| :--- | :--- | -| **Metric** | **Change** | -| engagements | We’ve updated the metrics that roll into overall engagements to match consistency with the Post analytics dashboard. Engagements measures “times people interacted with this Post”.

For Posts that include media like a video or a GIF, the engagements metric will no longer include media views. Media views can now be accessed in a new metric, _media_views_. | -| media_clicks* | This metric has been replaced by a new metric called “_media_engagements_”. | -| video_views | As of July 6th, 2018, this metric is now available for 'unowned' Posts via the [/totals](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement) endpoint. This means that you can access the video views for **all** Posts by using app-only authentication. 

You can only request video views that are younger than 1800 days old. If you try to request video views for a Post older than 1800 days, you will receive the following:

"unsupported\_for\_video\_views\_tweet\_ids": \["TWEET\_ID"\]

**Please note** that it will differ from media\_views in that video\_views relies on the MRC standard of 50% of the video in view for at least two seconds.

**Also,** note that you may see a discrepancy between the video views metric displayed in the X owned and operated platforms (mobile app and website) and the number that you receive via the /28hr and /historical endpoints.

* The video views displayed in the X user interface and that delivers using the /totals endpoint will display the video view aggregated across all Posts in which the given video has been posted. That means that the metric displayed in the UI includes the combined views from any instance where the video has been Retweeted or reposted in separate Posts.
* The video views provided by the /28hr and /historical endpoints will just include those views generated by the specific Post for which you are pulling metrics. | -| media_views | This includes all views (autoplay and click) of your media counted across videos, vines, gifs, and images.

**Please note** that Posts with images do not show a media_views metric in the analytics dashboard but will be returned in the Engagement API. | -| media_engagements* | This includes the number of clicks on your media across videos, vines, gifs, and images. This metric is replacing _media_clicks_. | -| quote_tweets | As of July 7th, 2020, this metric is now available for 'unowned' Posts via the /totals endpoint. This means that you can access the Quote Post count for all Posts by using app-only authentication. | - - -### Interpreting the metrics - -**Note:** You may observe differences between reported data on some of the X web dashboards, and the data reported in the Engagement API. These differences occur because the web dashboards typically only show engagements and/or impressions that occurred within the selected time range. For example, a web dashboard may show engagement on Posts within the span of a calendar month, while the Engagement API may show engagements that fall beyond the span of that month, but within the time range requested. The Engagement API should be seen as the valid source, in these cases. -  - -#### Impressions and engagement data - -The Engagement API delivers **organic** impressions and engagement data. - -Impressions represent the number of times that a given Post has been viewed on the X platform in an organic context. Impressions generated from Posts that are seen in a Promoted or Paid context are **not** included. - -Engagements represent the number of times that a given Post was engaged upon by a viewer in both an **organic** and **promoted** context. Engagements include, but are not limited to, Retweets, Favorites, Replies, URL Clicks, Hashtag Clicks, Mention Clicks, and Media Views. For the full list of included engagement actions, please see the Engagement Data section.  - -In order to calculate a baseline engagement rate, please use the total number of engagements divided by the total number of impressions for a given Post for the time period you are analyzing. - -Impression and engagement data can only be retrieved for Posts from owned @handles, or @handles that have authorized your application to view details about their Posts.  Internally, the Engagement API will track the number of unique @handles that have been requested against the contracted @handle limit.  It's recommended to also track the @handle request usage on the client side throughout the month.   - - -#### Video metrics - -There are a couple of different metrics that represent impressions of media within X. The first of which is our video views metric, which relies on the MRC standard of 50% of the video in view for at least two seconds. The second is Media Views, that includes all views (autoplay and click) of your media counted across videos, vines, gifs, and images. - -The video views metric is available for owned Posts via the /28hour and /historical endpoints, as well as for all unowned Posts via the /totals endpoint.  - -While the video views metric within the X user interface is using the same MRC standard, please note that you may see a discrepancy between the video views metric displayed in the X owned and operated platforms (mobile app and website) and the number that you receive via the different Engagement API endpoints. - -* The video views provided by the /totals endpoint and the X user interface will display the video view aggregated across all Posts in which the given video has been posted. That means that the metric delivered via /totals and displayed in the X UI includes the combined views from any instance where the video has been Retweeted or reposted in separate Posts. -* The video views provided by the /28hour and /historical Engagement API endpoints will just include those views generated by the specific Post for which you are pulling metrics.  -   - -Please note that we do not deliver video views for Posts that are older than 1800 days. Instead, we deliver an object that lists the Posts that are older than 1800 days. You will still receive all other metrics for your requested Posts in a separate object. Here is an example response: - -```json -{ - "unsupported_for_video_views_tweet_ids": [ - "479311209565413376", - "477139122520219648" - ], - "grouping name": { - "479311209565413376": { - "favorites": "69", - "impressions": "1692", - "retweets": "142", - "video_views": "0" - }, - "477139122520219648": { - "favorites": "10", - "impressions": "1023", - "retweets": "6", - "video_views": "0" - }, - "1397568983931392004": { - "favorites": "268", - "impressions": "26803", - "retweets": "56", - "video_views": "17902" - } - } -} -``` - -The Media Views metric is only available for owned Posts with the /28hour and /historical endpoints. - - -### Engagement API groupings - -Groupings enable custom organization of the returned engagement metrics. You can include a maximum of 3 groupings per request. You can choose to group the metrics by one or more of the following values: - -_All three endpoints support:_ - -* tweet.id -* engagement.type -   - -_The `/28hr` and `/historical` can provide time-series metrics, and thus support:_ - -* engagement.day -* engagement.hour - -Groupings are honored serially, so that you can change the desired result format by changing the order of your `group_by` values. Groupings that contain four `group_by` values will only be supported in one of the following two formats: -  -```bash -"group_by": [ - "tweet.id", - "engagement.type", - "engagement.day", - "engagement.hour" - ] -``` - -OR - -```bash -"group_by": [ - "engagement.type", - "tweet.id", - "engagement.day", - "engagement.hour" -] -``` - -For example, if you want to generate grand totals of metric types, include the following “groupings” specification as part of your request (and see the [API Reference](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#post-insights-engagement) page for more information on assembling requests): -  -```json -{ - "engagement_types": [ - "favorites", - "replies", - "retweets" - ], - "groupings": { - "Grand Totals": { - "group_by": [ - "engagement.type" - ] - } - } -} -``` - -With this grouping, the Engagement API’s JSON response will include a root-level `"Grand Totals"` attribute which contains grand totals by metrics type: -```json -{ - "Grand Totals": { - "favorites": "12", - "replies": "2", - "retweets": "2" - } -} -``` - -To generate a 4-hour time-series of metrics for a single Post grouped by Post IDs, the following Grouping specification would be part of the request: - -```json -{ - "start": "2016-02-10T17:00:00Z", - "end": "2016-02-10T21:00:00Z", - "tweet_ids": [ - "697506383516729344" - ], - "engagement_types": [ - "impressions", - "engagements" - ], - "groupings": { - "Tweets_MetricType_TimeSeries": { - "group_by": [ - "tweet.id", - "engagement.type", - "engagement.hour" - ] - } - } -} -``` - -With this grouping, the Engagement API’s JSON response will include a root-level `"Tweets_MetricType_TimeSeries"` attribute which contains the metrics broken down by Post ID, then metric type, and the corresponding hourly time-series: - -```json -{ - "Tweets_MetricType_TimeSeries": { - "697506383516729344": { - "impressions": { - "2016-02-10": { - "17": "551", - "18": "412", - "19": "371", - "20": "280" - } - }, - "engagements": { - "2016-02-10": { - "17": "8", - "18": "6", - "19": "3", - "20": "0" - } - } - } - } -} -``` - -## Frequently asked questions - -`Enterprise` - -### Engagement API - - - - Access to the Engagement API is provisioned through an enterprise subscription.  Please fill out [this form](/x-api/enterprise-gnip-2.0/enterprise-gnip) to get in touch with our sales team. - - - If your contract includes a limit for the number of unique handles that can be used with Engagement API.  The internal X system will keep track of the number of Authenticated users owning Posts that are queried with the Engagement API.  Customers should also keep track of this unique number on the client side.  Currently, there is no usage API or UI to check the @handle usage for the Engagement API.  The system will not block overages if there are more @handles requested than what is contracted.  At the end of the billing month, the number of unique @handles queried is compared to the contracted amount and an overage will be charged in accordance with the contract terms. - - -Currently, there is no usage API or UI to check the @handle usage for the Engagement API.  The system will not block overages if there are more @handles requested than what is contracted.  At the end of the billing month, the number of unique @handles queried is compared to the contracted amount and an overage will be charged in accordance with the contract terms. - -**The `engagements` metadata field returned in the payload is not equal to the sum of all the various engagement metric totals. Why is this the case?** - -This is to be expected. The `engagements` metadata field may not always correlate with the sum of all individual engagement metrics returned by the API. This is because the `engagements` metadata field may include additional engagements that do not have specific metrics broken out in the payload. Said another way, adding all of the various engagement metric totals together may not equal the value you are seeing in the `engagements` metric field that is returned to you in the payload. - -You can think of the `engagements` metadata field as any click or interaction made on the Post. -  - -**The `url_clicks` field in the payload response is returning a number, when in fact the Post does not have a URL. How is this possible?** - -This may be because a Post that contains something like a hashtag (that creates a link to another page) will count as a URL click if it is clicked on by a user. -  - - -There are various reasons why you might not be able to retrieve engagement data for a specific Post, including: - -* The Post ID or IDs you have requested are not available based on the authentication token you are using to retrieve data on behalf of a third party. -* The Post ID or IDs you have requested specific to the /totals endpoint are not 90 days or newer and are thus not available for returning the impressions or engagement metrics. -* The Post ID or IDs you have requested are no longer available, usually indicating that they have been deleted or are no longer publicly available for another reason. - -Please review the different [error messages](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#error-messages) that you will likely receive in any of the above cases. - - -You can use the `x-per-minute-limit` and `x-per-minute-remaining` information returned by the response header when you make a request to the Engagement API to monitor your consumption. - -`x-per-minute-limit` tells you what your allowance is and `x-per-minute-remaining` tells you how many calls you have left. - - - - -### Error troubleshooting guide - - - - Please make sure to review our [guidelines on authenticating](/x-api/enterprise-gnip-2.0/fundamentals/engagement-api#authentication) with the Engagement API. - - -```bash -[ - Your account could not be authenticated. Reason: Unknown Authorization Type; -] -``` -Make sure not to use any access tokens or secrets when you try and authenticate with the /totals endpoint. This is because if you do include these tokens, and are attempting to pull content from a Post not associated with these tokens, you will likely receive an error such as: -```bash -[ - Forbidden to access tweets: 1054424731825229824; -] -``` - - -### Still can't find what you're looking for? - - -Please reach out to technical support and we will respond to you promptly. - - - -## API reference - -### **POST insights/engagement** - - -#### **Methods** - -| Method | Description | -| :--- | :--- | -| [POST /insights/engagement/totals](#Totals) | Retrieve total impressions and engagements for a collection of Tweets. | -| [POST /insights/engagement/historical](#Historical) | Retrieve impressions and engagements for a collection of Tweets for a period up to 4 weeks in duration, back to September 1, 2014. | -| [POST /insights/engagement/28hr](#api-28hr) | Retrieve impressions and engagements for a collection of Tweets for the past 28 hours. | - -#### **Authentication** - -The Engagement API requires the use of HTTPS and supports the use of both User Context and Application-Only OAuth. Most requests to the Engagement API require the use of 3-Legged OAuth (A specific version of User Context), meaning that you use the consumer key and secret of the app that has been registered and approved for Engagement API access by your Twitter account manager, as well as the Tweet owners' access token and access token secret to call the endpoint. The following requests require this type of OAuth: - -* Any request to /totals to obtain Impressions and Engagements metric types, which are limited to owned Tweets -* Any request to /28hr -* Any request to /historical - -Some requests to the Engagement API can be performed using Application-Only OAuth, meaning that you just need to provide your consumer key and secret, or a bearer token. The following request can be performed with this type of OAuth: - -* Any request to /totals to obtain Favorites, Replies, Retweets, or Video Views metric types, which can be retrieved for any Tweet - -For any request, you will need to set up a Twitter app and corresponding API key using the app management console available at [developer.x.com](https://developer.x.com/en/portal/dashboard). - -Please note - You can view and edit your existing [Twitter apps](/resources/fundamentals/developer-apps) via the [Twitter app dashboard](https://developer.x.com/en/apps) if you are logged into your Twitter account on developer.x.com. - -Once you have set up your app, the app ID will need to be approved by your account representative in order for your app to make requests to the Engagement API. Access tokens must be used to represent the “current user”, and requests made on behalf of a separate user must be signed with a valid token. Ensure that you’re [encoding reserved characters](https://tools.ietf.org/html/rfc3986) appropriately within URLs and POST bodies before preparing OAuth signature base strings. - -For more information on how to get started with OAuth, please visit the following links: - -* [OAuth Overview](/resources/fundamentals/authentication) -* [Using 3 Legged OAuth, also known as User Context](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) -* [Using Application-Only OAuth](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only) - -#### **POST /insights/engagement/totals** - -The totals endpoint provides the ability to retrieve current total impressions and engagements for a collection of up to 250 Tweets at a time. - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | `https://data-api.x.com/insights/engagement/totals` | -| **Content Type** | `application/json` | -| **Compression** | Gzip. To make a request using Gzip compression, send an Accept-Encoding header in the connection request.
The header should look like the following:

`Accept-Encoding: gzip` | -| **POST Format** | Requests can be sent as a POST request where the body is a JSON object containing a collection of Tweet IDs and a desired grouping. The POST is formatted as an array with a `tweets`, `engagements`, and `groupings` object. Each request can have a maximum of 250 Tweet IDs.

An example POST body looks like:


\{
"tweet_ids": \[
"Tweet ID 1",
"Tweet ID 2",
"Tweet ID 3"
\],
"engagement_types": \[
"impressions",
"engagements",
"favorites",
"quote_tweets"
\],
"groupings": \{
"grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
}
} | -| **Tweet IDs** | An array that includes the Tweet IDs for the Tweets to be queried for engagement data. Please note that you are only able to request data for Tweets that were created by the authenticating @handle. Up to 250 Tweets may be included per request, and Tweet IDs must be represented as strings. | -| **Engagement Types** | An array that includes the types of engagement metrics to be queried. The Totals endpoint supports only the following engagement types: `impressions`, `engagements`, `favorites`, `retweets`, `quote_tweets`, `replies`, `video_views`.
The `/totals` endpoint supports the ability to retrieve `impressions` and `engagements` for Tweets created within the last 90 days, and `favorites`, `retweets`, `quote_tweets`, `replies`, and `video_views` for any Tweet. | -| **Groupings** | Results from the Engagement API can be returned in different groups to best fit your needs. You can include a maximum of 3 groupings per request.

For each grouping, you may define a custom grouping name to make it easier to refer to this grouping type in your application.

Once you have defined a grouping name, you can choose to group `tweet.id` and/or `engagement.type`.

Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. An example grouping that will show metrics separated by Tweet ID and metric type looks like:


"groupings": \{
"my grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
} | -| **POST Size Limit** | Requests can be made for a maximum of 250 Tweet IDs at a time. | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | You will be rate limited by minute, as specified in your contract according to your level of access. | -| **Example Request (public metrics)** | curl --request POST
--url https://data-api.x.com/insights/engagement/totals
--header 'accept-encoding: gzip'
--header 'authorization: Bearer '
--header 'content-type: application/json'
--data '\{
"tweet_ids": \[
"1070059276213702656","1021817816134156288","1067094924124872705"
\],
"engagement_types": \[
"favorites","retweets","replies","quote\_tweets","video\_views"
\],
"groupings": \{
"perTweetMetricsUnowned": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
}
}
--verbose
--compressed | -| **Example Request** | curl --request POST
--url https://data-api.x.com/insights/engagement/totals
--header 'accept-encoding: gzip'
--header 'authorization: OAuth oauth\_consumer\_key="consumer-key-for-app",oauth\_nonce="generated-nonce",oauth\_signature="generated-signature",oauth\_signature\_method="HMAC-SHA1", oauth\_timestamp="generated-timestamp",oauth\_token="access-token-for-authed-user", oauth_version="1.0"'
--header 'content-type: application/json'
--data '\{
"tweet_ids": \[
"1060976163948904448","1045709644067471360"
\],
"engagement_types": \[
"favorites","replies","retweets","video_views","impressions","engagements"
\],
"groupings": \{
"perTweetMetricsOwned": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
}
}'
--verbose
--compressed | -| **Example Response (public metrics)** | \{
"perTweetMetricsUnowned": \{
"1021817816134156288": \{
"favorites": "530",
"quote_tweets": "79",
"replies": "147",
"retweets": "323",
"video_views": "0"
},
"1067094924124872705": \{
"favorites": "1360",
"quote_tweets": "29",
"replies": "56",
"retweets": "178",
"video_views": "5754512"
},
"1070059276213702656": \{
"favorites": "69",
"quote_tweets": "5",
"replies": "7",
"retweets": "26",
"video_views": "0"
}
}
} | -| **Example Response** | \{
"perTweetMetricsOwned": \{
"1045709644067471360": \{
"engagements": "2",
"favorites": "0",
"impressions": "47",
"replies": "0",
"retweets": "8",
"quote_tweets": "5",
"video_views": "0"
},
"1060976163948904448": \{
"engagements": "4",
"favorites": "0",
"impressions": "148",
"replies": "1",
"retweets": "9",
"quote_tweets": "2",
"video_views": "0"
}
}
} | -| **Unavailable Tweet IDs** | For queries that include Tweet IDs that have been made unavailable (e.g., have been deleted), appropriate data will be returned for all available Tweet IDs, and unavailable Tweet IDs will be referenced in an array called `unavailable_tweet_ids`. For example:

\{
"start": "2015-11-17T22:00:00Z",
"end": "2015-11-19T02:00:00Z",
"unavailable\_tweet\_ids": \[
"323456789"
\],
"group1": \{
"423456789": \{
"favorites": "67",
"replies": "8",
"retweets": "26",
"quote_tweets": "2"
}
}
} | - -#### **POST /insights/engagement/28hr** - -The 28 hour endpoint provides the ability to retrieve impressions and engagements for a collection of up to 25 Tweets for the past 28 hours. The 28 hour endpoint also provides the ability to request metrics for all supported individual metrics. For the full list of supported metrics see [Metric Availability](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#EngagementTypes). - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | `https://data-api.x.com/insights/engagement/28hr` | -| **Content Type** | `application/json` | -| **Compression** | Gzip. To make a request using Gzip compression, send an Accept-Encoding header in the connection request.
The header should look like the following:

`Accept-Encoding: gzip` | -| **POST Format** | Requests can be sent as a POST request where the body is a JSON object containing a collection of Tweet IDs and a desired grouping. The POST is formatted as an array with a `tweets`, `engagements`, and `groupings` object. Each request can have a maximum of 25 Tweet IDs.

An example POST body looks like:


\{
"tweet_ids": \[
"Tweet ID 1",
"Tweet ID 2",
"Tweet ID 3"
\],
"engagement_types": \[
"impressions",
"engagements",
"url_clicks",
"detail_expands"
\],
"groupings": \{
"grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.hour"
\]
}
}
} | -| **Tweet IDs** | An array that includes the Tweet IDs for the Tweets to be queried for engagement data. Please note that you are only able to requests data for Tweets that were created by the authenticating @handle. The 28 hour endpoint supports up to a maximum of 25 Tweets per request, and Tweet IDs must be represented as strings. | -| **Engagement Types** | An array the types of engagement metrics to be queried.

For the 28 hour endpoint, `impressions`, `engagements`, and all individual engagement types are supported metrics. For the full list of supported engagement metrics see [Engagement Data](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#AvailableData). | -| **Groupings** | Results from the Engagement API can be returned in different groups to best fit your needs. You can include a maximum of 3 groupings per request.

For each grouping, you may define a custom grouping name to make it easier to refer to this grouping type in your application. Once you have defined a grouping name, you can choose to group by one or more of the following values:
`tweet.id`
`engagement.type`
`engagement.day`
`engagement.hour`
Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. An example grouping that will show metrics separated by Tweet ID, metric type, and looks like:

"groupings": \{
"my grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day"
\]
}
}


Groupings that have 4 `group_by` items are only valid if they use one of the following two orders. Requests that have 4 `group_by` items in a single grouping that are not one of the following will return an error. Additionally, only one grouping with 4 `group_by` items will be allowed per request.

"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day",
"engagement.hour"
\]

"group_by": \[
"engagement.type",
"tweet.id",
"engagement.day",
"engagement.hour"
\] | -| **POST Size Limit** | Requests can be made for a maximum of 25 Tweet IDs at a time. | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | You will be rate limited by minute, as specified in your contract according to your level of access. | -| **Example Request** | curl -X POST "https://data-api.x.com/insights/engagement/28hr"
-H 'Accept-Encoding: gzip'
-H 'Authorization OAuth oauth\_consumer\_key="consumer-key-for-app",oauth\_nonce="generated-nonce",oauth\_signature="generated-signature",oauth\_signature\_method="HMAC-SHA1", oauth\_timestamp="generated-timestamp",oauth\_token="access-token-for-authed-user", oauth_version="1.0"'
-d '\{
"tweet_ids": \[
"123456789"
\],
"engagement_types": \[
"impressions",
"engagements"
\],
"groupings": \{
"hourly-time-series": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day",
"engagement.hour"
\]
}
}
}' | -| **Example Response** | \{
"start": "2015-09-14T17:00:00Z",
"end": "2015-09-15T22:00:00Z",
"hourly-time-series": \{
"123456789": \{
"impressions": \{
"2015-09-14": \{
"17": "551",
"18": "412",
"19": "371",
"20": "280",
"21": "100",
"22": "19",
"23": "6"
},
"2015-09-15": \{
"00": "5",
"01": "2",
"02": "7",
"03": "3",
"04": "1",
"05": "0",
"06": "0",
"07": "0",
"08": "0",
"09": "0",
"10": "0",
"11": "0",
"12": "0",
"13": "0",
"14": "0",
"15": "0",
"16": "0",
"17": "0",
"18": "0",
"19": "0",
"20": "0",
"21": "0"
}
},
"engagements": \{
"2015-09-14": \{
"17": "0",
"18": "0",
"19": "0",
"20": "0",
"21": "0",
"22": "0",
"23": "0"
},
"2015-09-15": \{
"00": "0",
"01": "0",
"02": "0",
"03": "0",
"04": "0",
"05": "0",
"06": "0",
"07": "0",
"08": "0",
"09": "0",
"10": "0",
"11": "0",
"12": "0",
"13": "0",
"14": "0",
"15": "0",
"16": "0",
"17": "0",
"18": "0",
"19": "0",
"20": "0",
"21": "0"
}
}
}
}
} | -| **Unavailable Tweet IDs** | For queries that include Tweet IDs that have been made unavailable (e.g., have been deleted), appropriate data will be returned for all available Tweet IDs, and unavailable Tweet IDs will be referenced in an array called `unavailable_tweet_ids`. For example:

\{
"start": "2015-11-17T22:00:00Z",
"end": "2015-11-19T02:00:00Z",
"unavailable\_tweet\_ids": \[
"323456789"
\],
"group1": \{
"423456789": \{
"favorites": "67",
"replies": "8",
"retweets": 26
}
}
} | - -#### **POST /insights/engagement/historical** - -The historical endpoint provides the ability to retrieve impressions and engagements for a collection of up to 25 Tweets for any period up to 4 weeks in duration. Currently, data older than September 1, 2014 cannot be requested from the API. The historical endpoint also provides the ability to request metrics for all supported individual metrics. For the full list of supported metrics see [Metric Availability](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#EngagementTypes). - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | `https://data-api.x.com/insights/engagement/historical` | -| **Content Type** | `application/json` | -| **Compression** | Gzip. To make a request using Gzip compression, send an Accept-Encoding header in the connection request.
The header should look like the following:

`Accept-Encoding: gzip` | -| **POST Format** | Requests can be sent as a POST request where the body is a JSON object containing a collection of Tweet IDs and a desired grouping. The POST is formatted as an array with a `tweets`, `engagements`, and `groupings` object. Each request can have a maximum of 25 Tweet IDs. Each request can be specified with a custom Start and End date up to four weeks in duration.


\{
"tweet_ids": \[
"Tweet ID 1",
"Tweet ID 2",
"Tweet ID 3"
\],
"engagement_types": \[
"impressions",
"engagements",
"url_clicks",
"detail_expands"
\],
"groupings": \{
"grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.hour"
\]
}
}
} | -| **Start and End Date** | A custom start and end date can be specified with the `start` and `end` values as part of the request. You must specify a start and end date that are not longer than 4 weeks in duration. The oldest possible start date at this time is September 1, 2014. End dates in the future are not supported. If no Start and End date are supplied, the API will default to the immediately previous 4 weeks.

The lowest granularity that data can be returned from the Engagement API is by hour. For any requests made with Start or End values that do not fall directly on an hourly boundary, requests will default to the nearest inclusive hour. For instance, a request with "start":"2015-07-01T12:24:00Z" and "end":"2015-07-10T08:37:00Z" will default to "start":"2015-07-01T12:00:00Z","end":"2015-07-10T09:00:00Z". | -| **Tweet IDs** | An array that includes the Tweet IDs for the Tweets to be queried for engagement data. Please note that you are only able to requests data for Tweets that were created by the authenticating @handle. The 4 week historical endpoint supports up to a maximum of 25 Tweets per request, and Tweet IDs must be represented as strings. | -| **Engagement Types** | n array that includes the types of engagement metrics to be queried.

For the 4 week historical endpoint, `impressions`, `engagements`, and all individual engagement types are supported metrics. For the full list of supported engagement metrics see [Engagement Data](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overview#AvailableData).

\*\*Note:\*\*Currently there are three metrics that will display as zero for queries made before September 15, 2015: `favorites`, `replies`, and `retweets`. | -| **Groupings** | Results from the Engagement API can be returned in different groups to best fit your needs. You can include a maximum of 3 groupings per request.

For each grouping, you may define a custom grouping name to make it easier to refer to this grouping type in your application. Once you have defined a grouping name, you can choose to group by one or more of the following values:
`tweet.id`
`engagement.type`
`engagement.day`
`engagement.hour`
Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. An example grouping that will show metrics separated by Tweet ID, metric type, and looks like:

"groupings": \{
"my grouping name": \{
"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day"
\]
}
}


Groupings that have 4 `group_by` items are only valid if they use one of the following two orders. Requests that have 4 `group_by` items in a single grouping that are not one of the following will return an error. Additionally, only one grouping with 4 `group_by` items will be allowed per request.

"group_by": \[
"tweet.id",
"engagement.type",
"engagement.day",
"engagement.hour"
\]

"group_by": \[
"engagement.type",
"tweet.id",
"engagement.day",
"engagement.hour"
\] | -| **POST Size Limit** | Requests can be made for a maximum of 25 Tweet IDs at a time. | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | You will be rate limited by minute, as specified in your contract according to your level of access. | -| **Example Request** | curl -XPOST "https://data-api.x.com/insights/engagement/historical"
-H 'Accept-Encoding: gzip'
-H 'Authorization OAuth oauth\_consumer\_key="consumer-key-for-app",oauth\_nonce="generated-nonce",oauth\_signature="generated-signature",oauth\_signature\_method="HMAC-SHA1", oauth\_timestamp="generated-timestamp",oauth\_token="access-token-for-authed-user", oauth_version="1.0"'
-d '\{
"start": "2015-08-01",
"end": "2015-08-15",
"tweet_ids": \[
"123456789",
"223456789",
"323456789"
\],
"engagement_types": \[
"impressions",
"engagements",
"url_clicks",
"detail_expands"
\],
"groupings": \{
"types-by-tweet-id": \{
"group_by": \[
"tweet.id",
"engagement.type"
\]
}
}
}' | -| **Example Response** | \{
"start": "2015-08-01T00:00:00Z",
"end": "2015-08-15T00:00:00Z",
"types-by-tweet-id": \{
"123456789": \{
"impressions": "0",
"engagements": "0",
"url_clicks": "0",
"detail_expands": "0"
},
"223456789": \{
"impressions": "788",
"engagements": "134",
"url_clicks": "30",
"detail_expands": "1323"
},
"323456789": \{
"impressions": "4",
"engagements": "0",
"url_clicks": "2",
"detail_expands": "0"
}
}
} | -| **Unavailable Tweet IDs** | For queries that include Tweet IDs that have been made unavailable (e.g., have been deleted), appropriate data will be returned for all available Tweet IDs, and unavailable Tweet IDs will be referenced in an array called `unavailable_tweet_ids`. For example:

\{
"start": "2015-11-17T22:00:00Z",
"end": "2015-11-19T02:27:50Z",
"unavailable\_tweet\_ids": \[
"323456789"
\],
"group1": \{
"423456789": \{
"favorites": "67",
"replies": "8",
"retweets": 26
}
}
} | - -#### **Response codes** - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful. | -| 400 | Bad Request | Generally, this response occurs due to the presence of invalid JSON in the request, or where the request failed to send any JSON payload. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Check your OAuth keys and tokens. | -| 404 | Not Found | The resource was not found at the URL to which the request was sent, likely because an incorrect URL was used. | -| 429 | Too Many Requests | Your app has exceeded the limit on API requests. | -| 500 | Internal Server Error | There was an error on Gnip's side. Retry your request using an exponential backoff pattern. | -| 502 | Proxy Error | There was an error on Gnip's side. Retry your request using an exponential backoff pattern. | -| 503 | Service Unavailable | There was an error on Gnip's side. Retry your request using an exponential backoff pattern. | - -#### **Error Messages** - -In various scenarios, the Engagement API will occur situation-specific error messages that your application should be equipped to deal with. The table below includes common examples of these error messages and how you should interpret them. Please note that in many cases the Engagement API will return partial results for available data with specific error messages as part of a 200 OK response with more information. - -| Error Message | Description | -| :--- | :--- | -| `"errors":["Your account could not be authenticated. Reason: Access token not found"]` | An error in the authentication component of the request. The “Reason” should provide information that is helpful to troubleshoot the error. In cases where you are not able to resolve, please send the full error, including the “Reason”, to our support team. | -| `"errors":["1 Tweet ID(s) are unavailable"],"unavailable_tweet_ids": ["TWEET_IDS"]` | The Tweet ID or IDs you have requested are no longer available, usually indicating that they have been deleted or are no longer publicly available for another reason. | -| `"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*]` | The Tweet ID or IDs you have requested specific to the /totals endpoint are not 90 days or newer and are thus not available for returning the impressions or engagements metrics. | -| `"errors":["Forbidden to access tweets: *TWEET_IDS*"]` | The Tweet ID or IDs you have requested are not available based on the authentication token you are using to retrieve data on behalf of a third party. | +* Array specifying the [metric types](https://developer.x.com/en/docs/x-api/v1/metrics/get-tweet-engagement/overvie \ No newline at end of file diff --git a/x-api/enterprise-gnip-2.0/fundamentals/firehouse.mdx b/x-api/enterprise-gnip-2.0/fundamentals/firehouse.mdx index 3784784d1..7907216eb 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/firehouse.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/firehouse.mdx @@ -1,7 +1,8 @@ --- title: Compliance Firehose API keywords: ["compliance firehose", "firehose API", "compliance API", "enterprise firehose", "compliance stream", "firehose"] ---- + +description: >**Please note** > >We have released a new compliance tool to X API v2 called [batch compliance](/x-api/compliance/batch-compliance). This new tool allo...--- >**Please note** > @@ -274,109 +275,4 @@ See the payload examples below for each compliance event described in the table ``` ### integrating Compliance Firehose -The Compliance Firehose is a realtime streaming API that delivers compliance events that occur on the X platform. For an understanding of compliance events and how they are generated on X, please reference our article, [Honoring User Intent on X](/x-api/enterprise-gnip-2.0/fundamentals/firehouse#honoring-user-intent-on-twitter). - -It is important to note that Post and User events are delivered independently and that each should be processed independently (i.e. a Post delete doesn’t imply a User event, and vice versa.) Several User events are not necessarily permanent and can toggle between states infinitely. These include: user\_delete,user\_undelete, user\_protect, user\_unprotect and user\_suspend, user\_unsuspend. - -User\_deletes are followed by status\_deletes 30 days later only if the user has not selected to user\_undelete their account. It is possible that a user\_delete is reversed by the user and deletes for all of their Posts 30 days later do not occur. - -User\_suspend is an action that remains true unless the user is subject to an user\_unsuspend event. These are not subject to any changes on a 30 day time period. - -It is never suitable to display compliance events directly to users of your software or to otherwise incorporate them into your products or customer experiences. They are intended solely for maintaining compliance and honoring the actions of X users. - -#### **Integrating with the Compliance Firehose** - -To integrate the Compliance Firehose into your system, you will need to build an integration that can do the following: - -1. Establish a streaming connection to each streaming API partition of the Compliance Firehose -2. Handle high data volumes – de-couple stream ingestion from additional processing using asynchronous processes -3. Reconnect to the stream partitions automatically when disconnected for any reason -4. Process compliance events that are relevant to Post and User data you have stored in accordance with the guidance presented above - - -### Honoring user intent on Twitter - -We believe that respecting the privacy and intent of X users is critically important to the long term health of one of the largest public, real-time information platforms in the world. X puts privacy controls in the hands of its users, giving individuals the ability to control their own X experience. As business consumers of X data, we have a collective responsibility to honor the privacy and actions of end users in order to maintain this environment of trust and respect. - -There are a variety of things that can happen to Posts and User accounts that impact how they are displayed on the platform. The actions that affect privacy and intent are defined at both the Status (Post) and User levels. These actions include: - -#### User - -| Action | Description | -| :--- | :--- | -| Protect Account | A X user can protect or unprotect their account at any time. Protected accounts require manual user approval of every person who is allowed to view their account's Posts. 
For more information, see [About Public and Protected Posts](https://support.x.com/articles/14016-about-public-and-protected-tweets). | -| Delete Account | A X user can decide to delete their account and all associated status messages at any time. X retains the account information for 30 days after deletion in case the user decides to undelete and effectively reactivate their account. | -| Scrub Geo | A X user can remove all location data from past Posts at any time. This known as “scrub geo”. | -| Suspend Account | X retains the right to suspend accounts that are in violation of the X Rules or if an account is suspected to have been hacked or compromised. Account suspensions can only be reversed (unsuspend) by X. | -| Withhold Account | X retains the right to reactively withhold access to certain content in a specific country from time to time. A withheld account can only be made unwithheld by X. 
For more information, see [Country Withheld Content](https://support.x.com/articles/20169222-country-withheld-content). | - -#### Status - -| Action | Description | -| :--- | :--- | -| Delete Status | A X user can delete a status at any point in time. Deleted statuses cannot be reversed and are permanently deleted. | -| Withhold Status | X retains the right to reactively withhold access to certain content in a specific country from time to time. A withheld status can only be made unwithheld by X. 
For more information, see [Country Withheld Content](https://support.x.com/articles/20169222-country-withheld-content). | - -#### Keeping Track of User and Status Changes - -The state of a User or Status can change at any time due to one of the actions above, and this impacts how consumers of X data are expected to treat the availability and privacy of all associated content. When these actions happen, a corresponding compliance message is sent that indicates that the state of a Status or User has changed. - -## API Reference - -### **GET compliance/firehose** - -#### Methods - -| Method | Description | -| :--- | :--- | -| [GET /compliance/:stream](#Connect) | Connect to the Data Stream | - -#### Authentication - -All requests to the Compliance Firehose API must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. - -#### GET /compliance/:stream - -Establishes a persistent connection to the Compliance firehose data stream, through which the compliance events will be delivered. - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **Connection Type** | Keep-Alive | -| **URL** | Found on the stream's API Help page of your dashboard, and resembles the following structure:


[https://gnip-stream.x.com/stream/compliance/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition=1](https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1)

**Note:** The "partition" parameter is required. You will need to connect to all 8 partitions, each containing 12.5% of the total volume, to consume the full stream. | -| **Compression** | Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following:

Accept-Encoding: gzip | -| **Character Encoding** | UTF-8 | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | 10 requests per 60 seconds. | -| **Read Timeout** | Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds. | -| **Support for Tweet edits** | All Tweet edits trigger a "tweet_edit" Compliance event. See the [Compliance Data Objects](/x-api/enterprise-gnip-2.0/fundamentals/firehouse#compliance-data-objects) documentation for more details. | - -**Example Curl Request** - -The following example request is accomplished using cURL on the command line: - -```bash -curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1" -``` - -_Note:_ the above request is only connecting to `partition=1` of the Compliance firehose - you'll need to connect to all 8 partitions to consume the entirety of this stream. - -#### Response Codes - -The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect. - -| Status | Text | Definition | -| :--- | :--- | :--- | -| 200 | Success | The connection was successfully opened, and new activities will be sent through as they arrive. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 406 | Not Acceptable | Generally, this occurs where your client fails to properly include the headers to accept gzip encoding from the stream, but can occur in other circumstances as well. Will contain a JSON message similar to "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end." | -| 429 | Rate Limited | Your app has exceeded the limit on connection requests. | -| 503 | Service Unavailable | Twitter server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support. | - -#### Other Recommendations & Best practices - -* **Build Data Storage Schemas That Store Numeric Tweet ID and User ID**: User messages require action to be taken on all Tweets from that User. Therefore, since all compliance messages are delivered only by numeric ID, it is important to design storage schemas that maintain the relationship between Tweet and User based on numeric IDs. Data consumers will need to monitor compliance events by both Tweet ID and User ID and be able to update the local data store appropriately. - -* **Build Schemas That Address All Compliance Statuses**: Depending on how compliance activities will be addressed in various applications, it may be required to add other metadata to the data store. For instance, data consumers may decide to add metadata to an existing database to facilitate restricting the display of content in countries affected by a status_withheld message. - -* **Handling Retweet Deletes**: Retweets are a special kind of Tweet where the original message is nested in an object within the Retweet. In this case, there are two Tweet IDs referenced in a Retweet -- the ID for the Retweet, and the ID for the original message (included in the nested object). When an original message is deleted, a Tweet delete message is issued for the original ID. Subsequent delete messages are NOT issued for all of the Retweets. The deletion of the original ID should be sufficient to delete all subsequent Retweets. +The Compliance Firehose is a realtime streaming API that delivers compliance events that occur on the X platform. For an understanding of compliance events and how they are generated on X, please reference our article, [Honoring User Intent on X](/x-api/enterprise-gnip-2.0/fundamentals/f \ No newline at end of file diff --git a/x-api/enterprise-gnip-2.0/fundamentals/overview.mdx b/x-api/enterprise-gnip-2.0/fundamentals/overview.mdx index 6b55b7a83..cc91c03bd 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/overview.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/overview.mdx @@ -1,7 +1,8 @@ --- title: Gnip console keywords: ["GNIP console", "enterprise console", "GNIP", "enterprise API", "GNIP API", "enterprise data", "GNIP platform"] ---- + +description: >The enterprise console (at console.--- ## Overview >The enterprise console (at console.gnip.com) is available to enterprise data customers with contracted enterprise API access. If you are not currently an enterprise data customer but would like more information, you can learn more about [enterprise data](https://developer.x.com/en/products/x-api/enterprise) here. diff --git a/x-api/enterprise-gnip-2.0/fundamentals/rate-limits.mdx b/x-api/enterprise-gnip-2.0/fundamentals/rate-limits.mdx index 3f7fba756..e97d87878 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/rate-limits.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/rate-limits.mdx @@ -1,7 +1,8 @@ --- title: "Rate limits: Enterprise" keywords: ["enterprise rate limits", "GNIP rate limits", "enterprise API limits", "rate limits enterprise", "enterprise throttling"] ---- + +description: Every day many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, limits are placed on the number of...--- ## Overview diff --git a/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering.mdx b/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering.mdx index e34b33192..a77b035b5 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering.mdx @@ -1,7 +1,8 @@ --- title: "Rules and filtering: Enterprise" keywords: ["enterprise rules", "GNIP rules", "enterprise filtering", "PowerTrack rules", "enterprise queries", "filter rules enterprise"] ---- + +description: Products utilizing enterprise operators deliver social data to you based on filtering rules you set up. Rules are made up of one or more ‘clauses’, wher...--- ## Getting started with enterprise rules and queries @@ -193,148 +194,4 @@ However, if you are using the [Search API](/x-api/enterprise-gnip-2.0/fundamenta Below are the operators available with PowerTrack and Historical PowerTrack. A subset of these are available with the 30-Day and Full-Archive search APIs. See [this table](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#operators-by-product) for a product-by-product list of available operators.  | Operator | Description | -|:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| keyword | Matches a keyword within the text body or URL of a Post. Keywords must start with either a digit (0-9) or any non-punctuation character.
Keyword matching is tokenized, meaning the keyword is matched against tokenized text of the Post body.
For strings with punctuation (e.g., "coca-cola"), use a quoted "exact phrase match".
_Example_: `(social OR pizza OR wildfire) -planet` | -| emoji | Matches an emoji within the body of a Post, using tokenized matching based on punctuation, symbol/emoji, and separator characters.
If an emoji has a variant, use quotes for exact matches.
_Example_: `(🍕 OR 💜 OR 🐢) -🤖` | -| "exact phrase match" | Matches an exact phrase within the body of a Post. Punctuation is treated as whitespace.
_Example_: `("social media" OR "developer.x.com" OR "wildfire911" OR "coca-cola") -"planet earth"` | -| # | Matches any Post with the specified hashtag. This is an exact match, meaning `#2016` will match posts with `#2016` but not `#2016election`.
_Example_: `(#social OR #pizza OR #2016election) -#planet` | -| @ | Matches any Post mentioning the specified username.
_Example_: `(@XDevelopers OR @api OR @twittereng) -@jack` | -| "keyword1 keyword2"~N | Proximity operator that matches a Post where keywords are within N tokens of each other.
Keywords in reverse order can be no more than N-2 tokens apart. N cannot be greater than 6.
_Example_: `"social media"~5 OR "API"~3` | -| contains: | Substring match for Posts with the specified substring in the body, regardless of tokenization.
Use double quotes for substrings with whitespace or punctuation.
_Example_: `(contains:social OR contains:"wikipedia.com") -contains:"buy now"` | -| from: | Matches any Post from a specific user by X numeric Account ID or username (excluding `@`).
_Example_: `(from:2244994945 OR from:api OR from:twittereng) -from:jack` | -| to: | Matches any Post replying to a specific user by X numeric Account ID or username (excluding `@`).
_Example_: `(to:2244994945 OR to:api OR to:twittereng) -to:jack` | -| url: | Performs a tokenized (keyword/phrase) match on expanded URLs of a post.
_Example_: `@XDevelopers url:"developer.x.com"` | -| url_title: | Performs a keyword/phrase match on the expanded URL HTML title metadata.
_Available only with PowerTrack and Historical PowerTrack._ | -| url_description: | Performs a keyword/phrase match on the expanded page description metadata.
_Available only with PowerTrack and Historical PowerTrack._ | -| url_contains: | Matches Posts with URLs containing the specified phrase or keyword.
Enclose search terms with punctuation in quotes.
_Example_: `(url_contains:"developer.x.com" OR url_contains:wildfire) -url_contains:reddit` | -| bio: | Matches a keyword or phrase within the user bio of a Post. This is a tokenized match within the 'description' field within the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object).
_Example_: `(bio:engineer OR bio:"wordpress.com" OR bio:🚀) -bio:troll`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| bio_name: | Matches a keyword within the user bio name of a Post. This is a tokenized match within a user’s “name” field in the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object).
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| bio_location: | Matches Posts where the User object's location contains the specified keyword or phrase.
This operator performs a tokenized match, similar to the normal keyword rules on the message body.
This location is part of the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object), and is the account's 'home' location.
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| statuses_count: | Matches Posts when the author has posted a number of statuses within the given range.
If a single number is specified, any number equal to or higher will match.
A range can be specified to match any number in the range (e.g., `statuses_count:1000..10000`).
_Example:_ `to:api statuses_count:10`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| followers_count: | Matches Posts when the author has a followers count within the given range.
If a single number is specified, any number equal to or higher will match.
A range can be specified to match any number in the range (e.g., `followers_count:1000..10000`).
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| friends_count: | Matches Posts when the author has a friends count (the number of users they follow) within the given range.
If a single number is specified, any number equal to or higher will match.
A range can be specified to match any number in the range (e.g., `friends_count:1000..10000`).
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| listed_count: | Matches Posts when the author has been listed within X a certain number of times within the given range.
If a single number is specified, any number equal to or higher will match.
A range can be specified to match any number in the range (e.g., `listed_count:10..100`).
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| $ | Matches any Post that contains the specified ‘cashtag’ entity.
_Example_: `($TWTR OR $TSLA OR $BRK.A) -$F`
_Note:_ The cashtag operator relies on X's ‘symbols’ entity extraction to match cashtags, rather than extracting it from the body itself. | -| retweets_of: | Matches Posts that are Retweets of a specified user.
Accepts both usernames and numeric X Account IDs (NOT Post status IDs).
_Example_: `(retweets_of:2244994945 OR retweets_of:api OR retweets_of:twittereng) -retweets_of:jack` | -| retweets_of_status_id: | Deliver only explicit Retweets of the specified Post. Use the ID of an original Post and not a Retweet.
_Example_: `retweets_of_status_id:1293593516040269825`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| in_reply_to_status_id: | Deliver only explicit replies to the specified Post.
_Example_: `in_reply_to_status_id:1293593516040269825`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| sample: | Returns a random sample of Posts that match a rule. The sample percentage must be an integer between 1 and 100.
The operator reduces the scope to X%, then the rule/filter is applied to that sampled subset.
_Example:_ `#happybirthday sample:5`
`"happy birthday"~5 sample:80`
_Note:_ Only available with PowerTrack and Historical PowerTrack. | -| source: | Matches any Post generated by the specified source application. The value can be the application name or the application’s URL.
_Example:_ `#happybirthday source:"X for iPhone"`
`"This is a test X from my TestingApp" source:MyTestAppName`
_Note:_ The source operator searches on the Post source attribute and cannot be used alone. | -| lang: | Matches Posts classified by X as being in a particular language. Posts are currently classified as only one language, so matching multiple languages yields no results. _Not recommended to use alone._ | - -The list below represents the current supported languages and their corresponding BCP 47 language indentifier: - -| | | | | -| :--- | :--- | :--- | :--- | -| Amharic: am | German: de | Malayalam: ml | Slovak: sk | -| Arabic: ar | Greek: el | Maldivian: dv | Slovenian: sl | -| Armenian: hy | Gujarati: gu | Marathi: mr | Sorani Kurdish: ckb | -| Basque: eu | Haitian Creole: ht | Nepali: ne | Spanish: es | -| Bengali: bn | Hebrew: iw | Norwegian: no | Swedish: sv | -| Bosnian: bs | Hindi: hi | Oriya: or | Tagalog: tl | -| Bulgarian: bg | Latinized Hindi: hi-Latn | Panjabi: pa | Tamil: ta | -| Burmese: my | Hungarian: hu | Pashto: ps | Telugu: te | -| Croatian: hr | Icelandic: is | Persian: fa | Thai: th | -| Catalan: ca | Indonesian: in | Polish: pl | Tibetan: bo | -| Czech: cs | Italian: it | Portuguese: pt | Traditional Chinese: zh-TW | -| Danish: da | Japanese: ja | Romanian: ro | Turkish: tr | -| Dutch: nl | Kannada: kn | Russian: ru | Ukrainian: uk | -| English: en | Khmer: km | Serbian: sr | Urdu: ur | -| Estonian: et | Korean: ko | Simplified Chinese: zh-CN | Uyghur: ug | -| Finnish: fi | Lao: lo | Sindhi: sd | Vietnamese: vi | -| French: fr | Latvian: lv | Sinhala: si | Welsh: cy | -| Georgian: ka | Lithuanian: lt | | - -Example: - -(@XDevelopers OR to:XDevelopers) lang:es - -**Note:** The language operator matches on the specific Post language determined by X and set as the lang Post attribute.  See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) for more information on X Entities JSON attributes.  If no language classification can be made for a Post, the Post lang will be set as ‘und’ (for undefined). - -| Operator | Description | -|:--------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| place | Matches Posts tagged with the specified location or X place ID.
Multi-word place names should be enclosed in quotes.
_Example:_ `(place:London OR place:"Great Britain") -place:USA`
`place:fd70c22040963ac7`
**Note:** See the [GET geo/search](https://developer.x.com/en/docs/x-api/v1/geo/places-near-location/api-reference/get-geo-search) public API endpoint for how to obtain X place IDs.
**Note:** Will not match on Retweets or Quote Tweets, as Retweet places are attached to the original Post. | -| place_country | Matches Posts where the country code associated with a tagged place/location matches the given ISO alpha-2 character code.
_Example:_ `place_country:GB OR place_country:AU OR place_country:CA`
**Note:** Will not match on Retweets or Quote Tweets, as Retweet places are attached to the original Post.
Valid ISO codes: [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). | -| point_radius:[lon lat radius] | Matches against the Exact Location (x,y) of the Post or a “Place” geo polygon within the defined radius.
* Radius: < 25mi
* Supported units: mi, km
* Longitude: ±180
* Latitude: ±90
Coordinates are in decimal degrees.
Arguments are bracketed, space-delimited.
_Example:_ `point_radius:[-105.27346517 40.01924738 0.5mi]`
_Example:_ `point_radius:[2.355128 48.861118 16km]`
**Note:** Will not match on Retweets or Quote Tweets. | -| bounding_box:[west_long south_lat east_long north_lat] | Matches against Exact Location or a “Place” geo polygon fully contained in a bounding box.
Arguments are bracketed, space-delimited.
Coordinates: decimal degrees (±180 long, ±90 lat).
Width and height must be < 25mi.
_Example:_ `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]`
**Note:** Will not match on Retweets or Quote Tweets. | -| profile_country | Matches Posts where the author’s profile geo country code matches a given ISO-3166-1-alpha-2 two-letter code. | -| profile_region | Matches on the “region” field from the author’s profile geo enrichment, an exact full string match.
Use double quotes for substrings containing whitespace or punctuation.
_Example:_ `profile_region:"New York"` | -| profile_locality | Matches on the “locality” field from the author’s profile geo enrichment, an exact full string match.
Use double quotes for substrings containing whitespace or punctuation.
_Example:_ `profile_locality:"San Francisco"` | -| profile_subregion | Matches on the “subRegion” field from the author’s profile geo enrichment, including specific counties or metro areas.
An exact full string match.
_Example:_ `profile_subregion:"Santa Clara County"` | -| has:geo | Matches Posts with Post-specific geo location data from X, including “geo” lat-long or “Place” location data with a display name and geo polygon.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:profile_geo | Matches Posts with any Profile Geo metadata, regardless of value.
Available alias: `has:derived_user_geo`.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:links | Matches Posts with a link or referenced media in the "text" object of the payload, including media and Quote Tweets.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| is:retweet | Delivers only explicit retweets. Can be negated to exclude retweets and deliver only original content.
This operator looks only for true Retweets and not Quoted Tweets.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| is:reply | Delivers only explicit replies. Can be negated to exclude replies.
PowerTrack matches replies to original Posts, replies in quoted Posts, and replies in Retweets.
Search API matches only replies to original Posts.
_Example:_ `@XDevelopers -is:reply` | -| is:quote | Delivers only Quote Tweets or Posts that reference another Post.
Can be negated to exclude Quote Tweets.
_Example:_ `@XDevelopers is:quote` | -| is:verified | Delivers only Posts from “verified” authors. Can be negated to exclude Posts from verified authors.
_Example:_ `@XDevelopers is:verified` | -| has:mentions | Matches Posts mentioning another X user.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:hashtags | Matches Posts containing a hashtag.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:media | Matches Posts containing a media url classified by X (e.g., pic.x.com).
Available alias: `has:media_link`.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:images | Matches Posts containing a media url (e.g., pic.x.com).
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:videos | Matches Posts containing native X videos uploaded to X.
Available alias: `has:video_link`.
This operator does not match videos from YouTube, Periscope, or other video hosting sites.
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | -| has:symbols | Matches Posts containing a cashtag symbol (e.g., $TWTR).
**Note:** With Search API, must be combined with non-`is:` or `has:` operators. | - - -## Operators by product -### Rules and filtering: Enterprise - -All enterprise operators are available with PowerTrack and Historical PowerTrack APIs. However, only a subset of operators are available to the enterprise Search APIs, as noted on this page. - -The dark blue tags note which operators are available to different enterprise products: - -PowerTrack Search - -| Operator | Product | Description | Matches on payload element | -| :--- | :--- | :--- | :--- | -| "exact phrase match" | PowerTrack

Search | Matches an exact phrase within the body of a Post.

Components that can translate into a search operators will be treated as words. In other words:

* `"#hashtag"` will match `hashtag` but not `#hashtag` (use the [hashtag operator](#hashtag-operator) without quotes to match on actual hashtags) 
* `"$TWTR"` will match the word `TWTR` but not the cashtag `$TWTR` (use the [cashtag operator](#cashtag-operator) without quotes to match on actual cashtags)

**Note:** in 30 Day Search and Full Archive Search (Enterprise and Premium), punctuation is not tokenized and is instead treated as whitespace. | `text` | -| @ | PowerTrack

Search | Matches any Post that mentions the given username. The value can be either the username (excluding the `@` character) or the user’s numeric ID or (obtained for example via the [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) endpoint). | `entities.user_mentions` | -| # | PowerTrack

Search | Matches any Post with the given hashtag.

This operator performs an exact match. For example meaning the rule `#1989` will match Posts containing the exact hashtag `#1989`, but not those with the hashtag `#TaylorSwift1989`.

**Note:** this operator relies on X's entity extraction to match hashtags, rather than extracting the hashtag from the body itself. For more details on JSON attributes from entities, refer to [X Entities](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary). | `entities.hashtags` | -| $ | PowerTrack

Search | Matches any Post that contains the specified cashtag (where the leading character of the token is `$`).

**Note: **this operator relies on X's entity extraction to match links, rather than extracting the link from the body itself. For more details on JSON attributes from entities, refer to [X Entities](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary). | `entities.symbols` | -| bio: | PowerTrack | _Available alias_: user_bio:

Matches a keyword (using tokenized match) or a phrase within the user bio of a Post. Use double quotes to match a phrase. In other words:

* `bio:software engineer` will match Posts with the keyword `engineer` from users with the word `software` in their bio
* `bio:"software engineer"` will match any Post posted by users with the phrase `software engineer` in their bio | `user``.description` | -| bio_location: | PowerTrack | _Available alias_: user\_bio\_location:

Matches Posts where the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object)'s location contains the specified keyword (using tokenized match) or phrase.

This location is a non-normalized, user-generated, free-form string, and is different from a Post's location (when available). | `user.location` | -| bio_name: | PowerTrack | Matches Posts where the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object)'s name contains the specified keyword (using tokenized match) or phrase. | `user.name` | -| bounding_box: | PowerTrack

Search | _Available alias_: geo\_bounding\_box:

Matches against the exact location (long, lat) of the Post (when present), and against a geo polygon (where the Place is fully contained within the defined region).

* west\_long south\_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude.
* east\_long and north\_lat represent the northeast corner of the bounding box, where east\_long is the longitude of that point, and north\_lat is the latitude.
* Width and height of the bounding box must be less than 25mi
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained within brackets, space delimited.

**Note:** operators matching on place (Post geo) will only include matches from original Posts. Retweets do not contain any place data. | `place` (original Posts only) | -| contains: | PowerTrack | Substring match for Posts that have the given substring in the body, regardless of tokenization. In other words, this does a pure substring match and does not consider word boundaries.

Use double quotes to match substrings that contain whitespace or punctuation. | `text` | -| <emoji> | PowerTrack

Search | Matches an emoji within the body of a Post.

This is a tokenized match, so your emoji will be matched against the tokenized text of the Post body. Tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Post with the text “I like 🍕” would be split into the following tokens: I, like, 🍕. These tokens would then be compared to the emoji used in your rule.

**Note:** if an emoji has a variant, you must use double quotes to add to a rule. | `text` | -| followers_count: | PowerTrack | Matches Posts when the author has a followers count within the given range.

* A single number (e.g. `followers_count:42`) will match any number equal to or greater than the value specified.
* A range (e.g. `followers_count:42..1337`) will match any number in the given range. | `user.followers_count` | -| friends_count: | PowerTrack | _Available alias_: following_count:

Matches Posts when the author has a friends count (the number of users they follow) that falls within the given range.

* A single number (e.g. `followers_count:42`) will match any number equal to or greater than the value specified.
* A range (e.g. `followers_count:42..1337`) will match any number in the given range. | `user.friends_count` | -| from: | PowerTrack

Search | Matches any Post from a specific user. The value can be either the username (excluding the `@` character) or the user’s numeric ID or (obtained for example via the [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) endpoint). | `user.id`, `user.id_str` (if using User ID)

`user.screen_name` (if using username) | -| has:geo | PowerTrack

Search | Matches Posts that have Post-specific geolocation data provided from X. This can be either “geo” lat-long coordinate, or a “location” in the form of a X [Place](https://dev.x.com/overview/api/places), with the corresponding display name, geo polygon, and other fields.

Cannot be used as a standalone operator.

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `place` (original Tweets only) | -| has:hashtags | PowerTrack

Search | Matches Posts that contain at least one hashtag.

Cannot be used as a standalone operator. | `entities.hashtags` | -| has:images | PowerTrack

Search | Matches Posts that contain at least one classified image URL.

Cannot be used as a standalone operator. | `entities.media` | -| has:lang | PowerTrack | Matches Posts that have been classified by X as being of a particular language.

If a Post has not been classified, the operator will not match. Each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results.

Cannot be used as a standalone operator. | `lang` when value is not `und` | -| has:links | PowerTrack

Search | This operator matches Posts which contain links in the Post body.

Cannot be used as a standalone operator.

**Note:** this operator relies on X's entity extraction to match links, rather than extracting the link from the body itself. For more details on JSON attributes from entities, refer to [X Entities](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary). | `entities.urls` | -| has:media | PowerTrack

Search | _Available alias_: has:media_link

Matches Posts that contain at least one classified media URL.

Cannot be used as a standalone operator. | `entities.media` | -| has:mentions | PowerTrack

Search | Matches Posts that mention another X user.

Cannot be used as a standalone operator. | `entities.user_mentions` | -| has:profile_geo | PowerTrack

Search | _Available alias_: has:derived\_user\_geo

Matches Posts that have any [Profile Geo](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) metadata, regardless of the actual value.

Cannot be used as a standalone operator. | `user.location` | -| has:symbols | PowerTrack

Enterprise | Matches Posts that contain a cashtag symbol (e.g. `$TWTR`).

Cannot be used as a standalone operator. | `entities.symbols` | -| has:videos | PowerTrack

Search | _Available alias_: has:video_link

Matches Posts that contain at least one classified media URL.

Cannot be used as a standalone operator. | `entities.media` | -| in\_reply\_to\_status\_id: | PowerTrack | _Available alias_: in\_reply\_to\_tweet\_id:

Deliver only explicit replies to the specified Post. | `id`, `id_str` of the target Post | -| is:quote | PowerTrack | Deliver explicit Quote Tweets that match a rule.

It can also be negated (`-is:quote`) to exclude Quote Tweets that match a rule from delivery.

Cannot be used as a standalone operator. | `is_quote_status` (if `true`) | -| is:reply | PowerTrack

Search | Deliver only replies that match a rule.

It can also be negated (`-is:reply`) to exclude delivery of replies that match the specified rule.

With PowerTrack, this operator matches on:

* Replies to an original Post
* Replies in quoted Posts
* Replies in Retweets


When used with the Search API, this operator matches on replies to an original Post, but excludes replies in quoted Tweets and replies in Retweets.

You can use this operators in conjunction with `is:retweet` and `is:quote` to only deliver replies to original Posts.

Cannot be used as a standalone operator with the Search API.

**Note**: with Premium, this operator is not available in Sandbox dev environments. | Reply elements, e.g. `in_reply_to_status_id` | -| is:retweet | PowerTrack

Search | Deliver only explicit Retweets that match a rule.

It can also be negated (`-is:retweet`) to exclude Retweets that match a rule from delivery and only original content is delivered.

This operator looks only for true Retweets (i.e. Retweets posted using the Retweet button). Quoted Tweets and modified Posts which do not use X's Retweet functionality will not be matched by this operator.

Cannot be used as a standalone operator. | Retweet elements, e.g. `retweeted_status` | -| is:verified | PowerTrack

Search | Deliver only Posts where the author is verified by X.

It can also be negated to exclude Posts where the author is verified.

Cannot be used as a standalone operator. | `user.verified` | -| keyword | PowerTrack

Search | Matches a keyword within the body of a Post.

This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body. Tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: `I`, `like`, `coca`, `cola`. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (e.g. coca-cola), symbol, or separator characters, you must use an [exact phrase match](#exact-match) operator. | `text` | -| lang: | PowerTrack

Search | Matches Posts that have been classified by X as being of a particular language (if, and only if, the post has been classified). Each Post will be classified with only one language, so AND’ing together multiple languages will yield no results.

**Note: **if no language classification can be made the provided result is `und` (for undefined).

This operator will only match against supported languages. Providing any other value (including `und`) will result in the operator being ignored (in other words, Posts will not be filtered by this operator). The list below represents the currently supported languages and their corresponding BCP 47 language identifier:

`am` Amharic

`hu` Hungarian

`pt` Portuguese

`ar` Arabic

`is` Icelandic

`ro` Romanian

`hy` Armenian

`in` Indonesian

`ru` Russian

`bn` Bengali

`it` Italian

`sr` Serbian

`bg` Bulgarian

`ja` Japanese

`sd` Sindhi

`my` Burmese

`kn` Kannada

`si` Sinhala

`zh` Chinese

`km` Khmer

`sk` Slovak

`cs` Czech

`ko` Korean

`sl` Slovenian

`da` Danish

`lo` Lao

`ckb` Sorani Kurdish

`nl` Dutch

`lv` Latvian

`es` Spanish

`en` English

`lt` Lithuanian

`sv` Swedish

`et` Estonian

`ml` Malayalam

`tl` Tagalog

`fi` Finnish

`dv` Maldivian

`ta` Tamil

`fr` French

`mr` Marathi

`te` Telugu

`ka` Georgian

`ne` Nepali

`th` Thai

`de` German

`no` Norwegian

`bo` Tibetan

`el` Greek

`or` Oriya

`tr` Turkish

`gu` Gujarati

`pa` Panjabi

`uk` Ukrainian

`ht` Haitian

`ps` Pashto

`ur` Urdu

`iw` Hebrew

`fa` Persian

`ug` Uyghur

`hi` Hindi

`pl` Polish

`vi` Vietnamese

`cy` Welsh | `lang` when value is not `und` | -| listed_count: | PowerTrack | _Available alias_: user\_in\_lists_count:

Matches Posts when the author has been listed on X a number of times falls within the given range.

* A single number (e.g. `listed_count:42`) will match any number equal to or greater than the value specified.
* A range (e.g. `listed_count:42..1337`) will match any number in the given range. | `user.listed_count` | -| place_country: | PowerTrack

Search | Matches Posts where the country code associated with a tagged [place/location](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-geo-objects) matches the given [ISO alpha-2 character code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

**Note:** operators matching on place (Post geo) will only include matches from original Posts. Retweets do not contain any place data. | `place` (original Posts only) | -| place: | PowerTrack

Search | Matches Posts tagged with specified location or [X place ID](https://developer.x.com/en/docs/x-api/v1/geo/places-near-location/api-reference/get-geo-search). Multi-word place names should be enclosed in quotes (e.g. `place:"San Francisco"`)

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `place` (original Posts only) | -| point_radius: | PowerTrack

Search | **Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `place` (original posts only) | -| profile\_bounding\_box:\[west\_long south\_lat east\_long north\_lat\] | PowerTrack | Matches against the user's exact Location (long, lat) in the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments) where the Place is fully contained within the defined region.

* west\_long south\_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude.
* east\_long and north\_lat represent the northeast corner of the bounding box, where east\_long is the longitude of that point, and north\_lat is the latitude.
* Width and height of the bounding box must be less than 25mi
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained within brackets, space delimited.

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `user.derived.locations.geo.coordinates` | -| profile_country: | PowerTrack

Search | Exact match on the country code from the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

Uses a normalized set of two-letter country codes, based on [ISO-3166-1-alpha-2 specification](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

To be concise, this operator is provided in lieu of an operator for the country field from the address object.

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `user.derived.locations.country_code` | -| profile_locality: | PowerTrack

Search | Exact match on the Locality field from the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

This is an exact full string match.

It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use `one/two`.

Use double quotes to match substrings that contain whitespace or punctuation, e.g. `profile_locality:"Lower East Side"`. | `user.derived.locations.locality` | -| profile\_point\_radius:\[lon lat radius\] | PowerTrack | Matches against the Exact Location (x,y) of the user's [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

* Units of radius supported are miles (mi) and kilometers (km).
* Radius must be less than 25mi.
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained within brackets, space delimited.

**Note:** operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. | `user.derived.locations.geo` | -| profile_region: | PowerTrack

Search | Exact match on the Region field from the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

This is an exact full string match.

It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use `one/two`.

Use double quotes to match substrings that contain whitespace or punctuation, e.g. `profile_locality:"New York"`. | `user.derived.locations.region` | -| profile_subregion: | PowerTrack | Exact match on the Subregion field from the [Profile Geo enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments).

This is an exact full string match.

It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use `one/two`.

Use double quotes to match substrings that contain whitespace or punctuation, e.g. `profile_locality:"Kings County"`. | `user.derived.locations.sub_region` | -| "keyword1 keyword2"~N | PowerTrack

Search | Commonly referred to as a proximity operator, this matches a Post where the keywords are no more than N tokens from each other.

If the keywords are in the opposite order, they can not be more than N-2 tokens from each other.

Can have any number of keywords in quotes.

N cannot be greater than 6. | `text` | -| retweets\_of\_status_id: | PowerTrack | _Available alias_: retweets\_of\_tweet_id:

Deliver only explicit Retweets of the specified original Post. | `retweeted_status.id`, `retweeted_status.id_str` | -| retweets_of: | PowerTrack

Search | _Available alias_: retweets\_of\_user:

Matches any Post that are Retweets of the given user. The value can be either the username (excluding the `@` character) or the user’s numeric ID or (obtained for example via the [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) endpoint). | `retweeted_status.id` (if present) | -| sample: | PowerTrack | Returns a random percent sample of Posts that match a rule rather than the entire set of Posts. The percent value must be represented by an integer between 1 and 100.

This operator applies to the entire rule and requires all OR'd terms to be grouped.

**Note:** the sample operator first reduces the scope of the firehose to X%, then the rule/filter is applied to that sampled subset. If you are using, for example, `sample:10`, each Post has a 10% chance of being in the sample. 

**Note:** the sampling is deterministic, and you will get the same data sample in realtime as you would if you pulled the data historically. | | -| source: | PowerTrack | Matches any Post generated by the given source application. The value must be either the name of the application or the application’s URL.

Cannot be used as a standalone operator. | `source` | -| statuses_count: | PowerTrack | _Available alias_: tweets_count:

Matches Posts when the author has posted a number of statuses that falls within the given range.

* A single number (e.g. `statuses_count:42`) will match any number equal to or greater than the value specified.
* A range (e.g. `statuses_count:42..1337`) will match any number in the given range. | `user``.statuses_count` | -| to: | PowerTrack

Search | Matches any Post that is in reply to a particular user. The value can be either the username (excluding the `@` character) or the user’s numeric ID or (obtained for example via the [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) endpoint). | `text` | -| url: | PowerTrack

Search | Performs a tokenized match on the expanded URLs of a Post. Tokens and phrases containing punctuation or special characters should be double-quoted (e.g. `url:"/developer"`).

While generally not recommended, the operator can also match on a specific protocol, enclosed in double-quotes (e.g. `url:"https://developer.x.com"`). | `entities.urls.expanded_url` | -| url_contains: | PowerTrack | Performs a keyword/phrase match on the (new) [expanded URL title metadata enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments). | `entities.urls.expanded_url` | -| url_description: | PowerTrack | _Available alias_: within\_url\_description:

Performs a keyword/phrase match on the (new) [expanded page description metadata enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments). | `entities.urls.unwound.description` | -| url_title: | PowerTrack | _Available alias_: within\_url\_title:

Performs a keyword/phrase match on the (new) [expanded URL title metadata enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments). | `entities.urls.title` | +|:---------------------------|:------------------------------------------------------------------------------------------------------------------------------------- \ No newline at end of file diff --git a/x-api/enterprise-gnip-2.0/fundamentals/search-api.mdx b/x-api/enterprise-gnip-2.0/fundamentals/search-api.mdx index 01c46bcd6..467b520e4 100644 --- a/x-api/enterprise-gnip-2.0/fundamentals/search-api.mdx +++ b/x-api/enterprise-gnip-2.0/fundamentals/search-api.mdx @@ -2,7 +2,8 @@ title: "Search API: Enterprise" sidebarTitle: Search API keywords: ["enterprise search", "GNIP search", "enterprise search API", "search API enterprise", "enterprise search endpoints"] ---- + +description: >**Please note:** > >We have released a new version of [search Posts](/x-api/posts/search/introduction) and [Post counts](/x-api/posts/counts/introducti...--- >**Please note:** > @@ -120,1346 +121,4 @@ If the request fails 4 times in a row, and you have waited at least 10 minutes b The enterprise Search Posts: 30-Day API provides you with Posts posted within the last 30 days. Posts are matched and sent back to you based on the query you specify in your request. A query is a rule in which you define what the Post you get back should contain. In this tutorial, we will search for Posts originating from the X account @XDevelopers in English. -The Posts you get back in your payload can be in a data format, which provides you with the full Post payload, or it can be in a counts format which gives you numerical count data of matched Posts. We will be using cURL to make requests to the data and counts endpoints. - -You will need the following: - -* [An enterprise account]https://developer.x.com/en/products/x-api/enterprise -* Your username, password, and account name -* Label associated with your search endpoint, as displayed at console.gnip.com - -#### Accessing the data endpoint - - -The data endpoint will provide us with the full Post payload of matched Posts. We will use the `from:` and `lang:` operators to find Posts originating from @XDevelopers in English. _For more operators [click here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-operators)._ - - -_cURL is a command-line tool for getting or sending files using the URL syntax._ - -Copy the following cURL request into your command line after making changes to the following: - -* **Username** `` e.g. `email@domain.com` - -* **Account name** `` e.g. `john-doe` - -* **Label** ` - - -```bash -_This is an example cURL request. If you try to run this it will not work._ - -curl -X POST -uemail@domain.com "https://gnip-api.x.com/search/30day/accounts/john-doe/prod.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"201811100000","toDate":"201812012359"}' -``` - - - -#### Data endpoint response payload - -The payload you get back from your API request will appear in JSON format, as shown below. -```json -{ - "results": [ - { - "created_at": "Fri Nov 02 17:18:31 +0000 2018", - "id": 1058408022936977409, - "id_str": "1058408022936977409", - "text": "RT @harmophone: \"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conv…", - "source": "Twitter Web Client<\/a>", - "truncated": false, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "Twitter Dev", - "screen_name": "TwitterDev", - "location": "Internet", - "url": "https:\/\/developer.x.com\/", - "description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https:\/\/devcommunity.com\/ ⌨️ #TapIntoTwitter", - "translator_type": "null", - "protected": false, - "verified": true, - "followers_count": 503828, - "friends_count": 1477, - "listed_count": 1437, - "favourites_count": 2199, - "statuses_count": 3380, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": "en", - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "null", - "profile_background_image_url": "null", - "profile_background_image_url_https": "null", - "profile_background_tile": null, - "profile_link_color": "null", - "profile_sidebar_border_color": "null", - "profile_sidebar_fill_color": "null", - "profile_text_color": "null", - "profile_use_background_image": null, - "profile_image_url": "null", - "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg", - "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "retweeted_status": { - "created_at": "Tue Oct 30 21:30:25 +0000 2018", - "id": 1057384253116289025, - "id_str": "1057384253116289025", - "text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relev… https:\/\/t.co\/w46U5TRTzQ", - "source": "Twitter Web Client<\/a>", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 175187944, - "id_str": "175187944", - "name": "Tyler Singletary", - "screen_name": "harmophone", - "location": "San Francisco, CA", - "url": "http:\/\/medium.com\/@harmophone", - "description": "SVP Product at @Tagboard. Did some Data, biz, and product @Klout & for @LithiumTech; @BBI board member; @Insightpool advisor. World's worst whiteboarder.", - "translator_type": "null", - "protected": false, - "verified": false, - "followers_count": 1982, - "friends_count": 1877, - "listed_count": 245, - "favourites_count": 23743, - "statuses_count": 12708, - "created_at": "Thu Aug 05 22:59:29 +0000 2010", - "utc_offset": null, - "time_zone": null, - "geo_enabled": false, - "lang": "en", - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "null", - "profile_background_image_url": "null", - "profile_background_image_url_https": "null", - "profile_background_tile": null, - "profile_link_color": "null", - "profile_sidebar_border_color": "null", - "profile_sidebar_fill_color": "null", - "profile_text_color": "null", - "profile_use_background_image": null, - "profile_image_url": "null", - "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg", - "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conversations in real-time and enabling voters to ask questions during debates,”  -- @adamostrow, @TEGNA\nLearn More: https:\/\/t.co\/ivAFtanfje", - "display_text_range": [ - 0, - 259 - ], - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https:\/\/t.co\/ivAFtanfje", - "expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4", - "display_url": "blog.tagboard.com\/twitter-and-ta…", - "unwound": { - "url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4", - "status": 200, - "title": "Twitter and Tagboard Collaborate to Bring Best Election Content to News Outlets With Tagboard…", - "description": "By Tyler Singletary, Head of Product, Tagboard" - }, - "indices": [ - 236, - 259 - ] - } - ], - "user_mentions": [ - { - "screen_name": "adamostrow", - "name": "Adam Ostrow", - "id": 5695942, - "id_str": "5695942", - "indices": [ - 204, - 215 - ] - }, - { - "screen_name": "TEGNA", - "name": "TEGNA", - "id": 34123003, - "id_str": "34123003", - "indices": [ - 217, - 223 - ] - } - ], - "symbols": [] - } - }, - "quote_count": 0, - "reply_count": 1, - "retweet_count": 6, - "favorite_count": 19, - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https:\/\/t.co\/w46U5TRTzQ", - "expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025", - "display_url": "twitter.com\/i\/web\/status\/1…", - "indices": [ - 117, - 140 - ] - } - ], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en" - }, - "is_quote_status": false, - "quote_count": 0, - "reply_count": 0, - "retweet_count": 0, - "favorite_count": 0, - "entities": { - "hashtags": [], - "urls": [], - "user_mentions": [ - { - "screen_name": "harmophone", - "name": "Tyler Singletary", - "id": 175187944, - "id_str": "175187944", - "indices": [ - 3, - 14 - ] - } - ], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [ - { - "tag": null - } - ] - } - ], - "requestParameters": { - "maxResults": 100, - "fromDate": "201811010000", - "toDate": "201811060000" - } -} -``` - -#### Accessing the counts endpoint - -With the counts endpoint, we’ll retrieve the number of Posts originating from the @XDevelopers account in English grouped by `day`. - - - -_cURL is a command-line tool for getting or sending files using the URL syntax._ - -Copy the following cURL request into your command line after making changes to the following: - -* **Username** `` e.g. `email@domain.com` - -* **Account name** `` e.g. `john-doe` - -* **Label** ` - - -_This is an example cURL request. If you try to run this it will not work._ - -```bash -curl -X POST -uemail@domain.com "https://gnip-api.x.com/search/30day/accounts/john-doe/prod/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"201811100000","toDate":"201812012359","bucket":"day"}' -``` - - - -#### Counts endpoint response payload - -The payload you get back from your API request will appear in JSON format, as shown below. -```json -{ - "results": [ - { - "timePeriod": "201811010000", - "count": 0 - }, - { - "timePeriod": "201811020000", - "count": 1 - }, - { - "timePeriod": "201811030000", - "count": 0 - }, - { - "timePeriod": "201811040000", - "count": 0 - }, - { - "timePeriod": "201811050000", - "count": 0 - } - ], - "totalCount": 1, - "requestParameters": { - "bucket": "day", - "fromDate": "201811010000", - "toDate": "201811060000" - } -} -``` -Great job! Now you've successfully accessed the enterprise Search Posts: 30-Day API. - -##### **Referenced articles** - -* [Introduction to Post objects](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) -* [Search operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-operators) -* [Post objects and payloads](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#post-object) - -### Getting started with enterprise Search Posts: Full-Archive API - -The enterprise Search Posts: Full-Archive API provides you with Posts since the first one posted in 2006. Posts are matched and sent back to you based on the query you specify in your request. A query is a rule in which you define what the Post you get back should contain. In this tutorial, we will search for Posts originating from the X account @XDevelopers in English. - -The Posts you get back in your payload can be in a data format, which provides you with the full Post payload, or it can be in a counts format which gives you numerical count data of matched Posts. We will be using cURL to make requests to the data and counts endpoints. - -You will need the following: - -* [An enterprise account]https://developer.x.com/en/products/x-api/enterprise -* Your username, password, and account name -* Label associated with your search endpoint, as displayed at console.gnip.com - -#### Accessing the data endpoint - - -The data endpoint will provide us with the full Post payload of matched Posts. We will use the `from:` and `lang:` operators to find Posts originating from @XDevelopers in English. _For more operators [click here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-operators)._ - -* [cURL](#tab1) -* [cURL example](#tab2) - - - -_cURL is a command-line tool for getting or sending files using the URL syntax._ - -Copy the following cURL request into your command line after making changes to the following: - -* **Username** `` e.g. `email@domain.com` - -* **Account name** `` e.g. `john-doe` - -* **Label** ` - -_This is an example cURL request. If you try to run this it will not work._ - -```bash -curl -X POST -uemail@domain.com "https://gnip-api.x.com/search/fullarchive/accounts/john-doe/prod.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"201802010000","toDate":"201802282359"}' -``` - - - - -##### Data endpoint response payload - -The payload you get back from your API request will appear in JSON format, as shown below. - -```json -{ - "results": [ - { - "created_at": "Fri Nov 02 17:18:31 +0000 2018", - "id": 1058408022936977409, - "id_str": "1058408022936977409", - "text": "RT @harmophone: \"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conv…", - "source": "Twitter Web Client<\/a>", - "truncated": false, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 2244994945, - "id_str": "2244994945", - "name": "Twitter Dev", - "screen_name": "TwitterDev", - "location": "Internet", - "url": "https:\/\/developer.x.com\/", - "description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https:\/\/devcommunity.com\/ ⌨️ #TapIntoTwitter", - "translator_type": "null", - "protected": false, - "verified": true, - "followers_count": 503828, - "friends_count": 1477, - "listed_count": 1437, - "favourites_count": 2199, - "statuses_count": 3380, - "created_at": "Sat Dec 14 04:35:55 +0000 2013", - "utc_offset": null, - "time_zone": null, - "geo_enabled": true, - "lang": "en", - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "null", - "profile_background_image_url": "null", - "profile_background_image_url_https": "null", - "profile_background_tile": null, - "profile_link_color": "null", - "profile_sidebar_border_color": "null", - "profile_sidebar_fill_color": "null", - "profile_text_color": "null", - "profile_use_background_image": null, - "profile_image_url": "null", - "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg", - "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "retweeted_status": { - "created_at": "Tue Oct 30 21:30:25 +0000 2018", - "id": 1057384253116289025, - "id_str": "1057384253116289025", - "text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relev… https:\/\/t.co\/w46U5TRTzQ", - "source": "Twitter Web Client<\/a>", - "truncated": true, - "in_reply_to_status_id": null, - "in_reply_to_status_id_str": null, - "in_reply_to_user_id": null, - "in_reply_to_user_id_str": null, - "in_reply_to_screen_name": null, - "user": { - "id": 175187944, - "id_str": "175187944", - "name": "Tyler Singletary", - "screen_name": "harmophone", - "location": "San Francisco, CA", - "url": "http:\/\/medium.com\/@harmophone", - "description": "SVP Product at @Tagboard. Did some Data, biz, and product @Klout & for @LithiumTech; @BBI board member; @Insightpool advisor. World's worst whiteboarder.", - "translator_type": "null", - "protected": false, - "verified": false, - "followers_count": 1982, - "friends_count": 1877, - "listed_count": 245, - "favourites_count": 23743, - "statuses_count": 12708, - "created_at": "Thu Aug 05 22:59:29 +0000 2010", - "utc_offset": null, - "time_zone": null, - "geo_enabled": false, - "lang": "en", - "contributors_enabled": false, - "is_translator": false, - "profile_background_color": "null", - "profile_background_image_url": "null", - "profile_background_image_url_https": "null", - "profile_background_tile": null, - "profile_link_color": "null", - "profile_sidebar_border_color": "null", - "profile_sidebar_fill_color": "null", - "profile_text_color": "null", - "profile_use_background_image": null, - "profile_image_url": "null", - "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg", - "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841", - "default_profile": false, - "default_profile_image": false, - "following": null, - "follow_request_sent": null, - "notifications": null - }, - "geo": null, - "coordinates": null, - "place": null, - "contributors": null, - "is_quote_status": false, - "extended_tweet": { - "full_text": "\"The innovative crowdsourcing that the Tagboard, Twitter and TEGNA collaboration enables is surfacing locally relevant conversations in real-time and enabling voters to ask questions during debates,”  -- @adamostrow, @TEGNA\nLearn More: https:\/\/t.co\/ivAFtanfje", - "display_text_range": [ - 0, - 259 - ], - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https:\/\/t.co\/ivAFtanfje", - "expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4", - "display_url": "blog.tagboard.com\/twitter-and-ta…", - "unwound": { - "url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4", - "status": 200, - "title": "Twitter and Tagboard Collaborate to Bring Best Election Content to News Outlets With Tagboard…", - "description": "By Tyler Singletary, Head of Product, Tagboard" - }, - "indices": [ - 236, - 259 - ] - } - ], - "user_mentions": [ - { - "screen_name": "adamostrow", - "name": "Adam Ostrow", - "id": 5695942, - "id_str": "5695942", - "indices": [ - 204, - 215 - ] - }, - { - "screen_name": "TEGNA", - "name": "TEGNA", - "id": 34123003, - "id_str": "34123003", - "indices": [ - 217, - 223 - ] - } - ], - "symbols": [] - } - }, - "quote_count": 0, - "reply_count": 1, - "retweet_count": 6, - "favorite_count": 19, - "entities": { - "hashtags": [], - "urls": [ - { - "url": "https:\/\/t.co\/w46U5TRTzQ", - "expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025", - "display_url": "twitter.com\/i\/web\/status\/1…", - "indices": [ - 117, - 140 - ] - } - ], - "user_mentions": [], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "possibly_sensitive": false, - "filter_level": "low", - "lang": "en" - }, - "is_quote_status": false, - "quote_count": 0, - "reply_count": 0, - "retweet_count": 0, - "favorite_count": 0, - "entities": { - "hashtags": [], - "urls": [], - "user_mentions": [ - { - "screen_name": "harmophone", - "name": "Tyler Singletary", - "id": 175187944, - "id_str": "175187944", - "indices": [ - 3, - 14 - ] - } - ], - "symbols": [] - }, - "favorited": false, - "retweeted": false, - "filter_level": "low", - "lang": "en", - "matching_rules": [ - { - "tag": null - } - ] - } - ], - "requestParameters": { - "maxResults": 100, - "fromDate": "201811010000", - "toDate": "201811060000" - } -} -``` - - -#### Accessing the counts endpoint - -With the counts endpoint, we’ll retrieve the number of Posts originating from the @XDevelopers account in English grouped by `day`. - - - -_cURL is a command-line tool for getting or sending files using the URL syntax._ - -Copy the following cURL request into your command line after making changes to the following: - -* **Username** `` e.g. `email@domain.com` - -* **Account name** `` e.g. `john-doe` - -* **Label** ` - -```bash -_This is an example cURL request. If you try to run this it will not work._ - -curl -X POST -uemail@domain.com "https://gnip-api.x.com/search/fullarchive/accounts/john-doe/prod/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"201802010000","toDate":"201802282359","bucket":"day"}' -``` - - - -#### Counts endpoint response payload - -The payload you get back from your API request will appear in JSON format, as shown below. -```json -{ - "results": [ - { - "timePeriod": "201811010000", - "count": 0 - }, - { - "timePeriod": "201811020000", - "count": 1 - }, - { - "timePeriod": "201811030000", - "count": 0 - }, - { - "timePeriod": "201811040000", - "count": 0 - }, - { - "timePeriod": "201811050000", - "count": 0 - } - ], - "totalCount": 1, - "requestParameters": { - "bucket": "day", - "fromDate": "201811010000", - "toDate": "201811060000" - } -} -``` -Great job! Now you've successfully accessed the enterprise Search Posts: Full-Archive API. - -##### Referenced articles - -* [Introduction to Post objects](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) -* [Search operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-operators) -* [Post objects and payloads](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#post-object) - -## Guides -### Building search queries - -### Enterprise operators - -Below is a list of all operators supported in X's enterprise search APIs: - -* **Enterprise** 30-day search API -* **Enterprise** Full-archive search API - -For a side-by-side comparison of available operators by product see [HERE](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#operators-by-product). - -|Operator|Description| -|:--------|:------------------| -| keyword | Matches a tokenized keyword within the body or urls of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (for example, coca-cola), symbol, or separator characters, you must use a quoted exact match as described below.

**Note:** With the Search API, accented and special characters are normalized to standard latin characters, which can change meanings in foreign languages or return unexpected results:
For example, "músic" will match “music” and vice versa.
For example, common phrases like "Feliz Año Nuevo!" in Spanish, would be indexed as "Feliz Ano Nuevo", which changes the meaning of the phrase.

**Note:** This operator will match on both URLs and unwound URLs within a Post. | -|emoji|Matches an emoji within the body of a Post. Emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Post with the text “I like ” would be split into the following tokens: I, like, . These tokens would then be compared to the emoji used in your rule. Note that if an emoji has a variant, you must use “quotations” to add to a rule. | -|"exact phrase match" |Matches the tokenized and ordered phrase within the body or urls of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters.

**Note:** Punctuation is not tokenized and is instead treated as whitespace.
For example, quoted “#hashtag” will match “hashtag” but not #hashtag (use the hashtag # operator without quotes to match on actual hashtags.
For example, quoted “$cashtag” will match “cashtag” but not $cashtag (use the cashtag $ operator without quotes to match on actual cashtags.
For example, "Love Snow" will match "#love #snow"
For example, "#Love #Snow" will match "love snow"

**Note:** This operator will match on both URLs and unwound URLs within a Post.| -|"keyword1 keyword2"~N|Commonly referred to as a proximity operator, this matches a Post where the keywords are no more than N tokens from each other.

If the keywords are in the opposite order, they can not be more than N-2 tokens from each other. Can have any number of keywords in quotes. N cannot be greater than 6.

Note that this operator is only available in the `enterprise` search APIs.| -|from:| Matches any Post from a specific user.
The value must be the user’s X numeric Account ID or username (excluding the @ character). See [HERE](/x-api/users/lookup/introduction) or [HERE](http://gettwitterid.com/) for methods for looking up numeric X Account IDs.| -|to:|Matches any Post that is in reply to a particular user.

The value must be the user’s numeric Account ID or username (excluding the @ character). See [HERE](/x-api/users/lookup/introduction) for methods for looking up numeric X Account IDs.| -|url:|Performs a tokenized (keyword/phrase) match on the expanded URLs of a Post (similar to url_contains). Tokens and phrases containing punctuation or special characters should be double-quoted. For example, url:"/developer". While generally not recommended, if you want to match on a specific protocol, enclose in double-quotes: url:"https://developer.x.com".
**Note:** When using PowerTrack or Historical PowerTrack, this operator will match on URLs contained within the original Post of a Quote Post. For example, if your rule includes url:"developer.x.com", and a Post contains that URL, any Quote Tweets of that Post will be included in the results. This is not the case when using the Search API.| -|#|Matches any Post with the given hashtag.

This operator performs an exact match, NOT a tokenized match, meaning the rule “2016” will match posts with the exact hashtag “2016”, but not those with the hashtag “2016election”

Note: that the hashtag operator relies on X's entity extraction to match hashtags, rather than extracting the hashtag from the body itself. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#hashtags) for more information on X Entities JSON attributes.| -|@|Matches any Post that mentions the given username.
The to: operator returns a subset match of the @mention operator.| -|$|Matches any Post that contains the specified ‘cashtag’ (where the leading character of the token is the ‘$’ character).

Note that the cashtag operator relies on X's ‘symbols’ entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#symbols) for more information on X Entities JSON attributes.

Note that this operator is only available in the `enterprise` search APIs.

| -|retweets_of:|_Available alias_: retweets\_of\_user:
Matches Posts that are retweets of a specified user. Accepts both usernames and numeric X Account IDs (NOT Post status IDs).See [HERE](/x-api/users/lookup/introduction) for methods for looking up numeric X Account IDs.| -|lang:|Matches Posts that have been classified by X as being of a particular language (if, and only if, the post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results.

**Note:** if no language classification can be made the provided result is ‘und’ (for undefined).

The list below represents the current supported languages and their corresponding BCP 47 language indentifier:
- -| | | | | -| :--- | :--- | :--- | :--- | -| Amharic: am | German: de | Malayalam: ml | Slovak: sk | -| Arabic: ar | Greek: el | Maldivian: dv | Slovenian: sl | -| Armenian: hy | Gujarati: gu | Marathi: mr | Sorani Kurdish: ckb | -| Basque: eu | Haitian Creole: ht | Nepali: ne | Spanish: es | -| Bengali: bn | Hebrew: iw | Norwegian: no | Swedish: sv | -| Bosnian: bs | Hindi: hi | Oriya: or | Tagalog: tl | -| Bulgarian: bg | Latinized Hindi: hi-Latn | Panjabi: pa | Tamil: ta | -| Burmese: my | Hungarian: hu | Pashto: ps | Telugu: te | -| Croatian: hr | Icelandic: is | Persian: fa | Thai: th | -| Catalan: ca | Indonesian: in | Polish: pl | Tibetan: bo | -| Czech: cs | Italian: it | Portuguese: pt | Traditional Chinese: zh-TW | -| Danish: da | Japanese: ja | Romanian: ro | Turkish: tr | -| Dutch: nl | Kannada: kn | Russian: ru | Ukrainian: uk | -| English: en | Khmer: km | Serbian: sr | Urdu: ur | -| Estonian: et | Korean: ko | Simplified Chinese: zh-CN | Uyghur: ug | -| Finnish: fi | Lao: lo | Sindhi: sd | Vietnamese: vi | -| French: fr | Latvian: lv | Sinhala: si | Welsh: cy | -| Georgian: ka | Lithuanian: lt | | - -||| -|:----|:---| -|place:|Matches Posts tagged with the specified location _or_ X place ID (see examples). Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes.

**Note:** See the [GET geo/search](https://developer.x.com/en/docs/x-api/v1/geo/place-information/overview) public API endpoint for how to obtain X place IDs.

**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.| -|place_country:|Matches Posts where the country code associated with a tagged [place](https://developer.x.com/en/docs/x-api/v1/geo/place-information/overview) matches the given ISO alpha-2 character code.

Valid ISO codes can be found here: [http://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.| -|point_radius:\[lon lat radius\]|Matches against the Exact Location (x,y) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region.

* Units of radius supported are miles (mi) and kilometers (km).
* Radius must be less than 25mi.
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained with brackets, space delimited.

**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet.| -|bounding\_box:\[west\_long south\_lat east\_long north_lat\]|_Available alias_: geo\_bounding\_box:

Matches against the Exact Location (long, lat) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region.

* west\_long south\_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude.
* east\_long and north\_lat represent the northeast corner of the bounding box, where east\_long is the longitude of that point, and north\_lat is the latitude.
* Width and height of the bounding box must be less than 25mi
* Longitude is in the range of ±180
* Latitude is in the range of ±90
* All coordinates are in decimal degrees.
* Rule arguments are contained with brackets, space delimited.
**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. -|profile_country:|Exact match on the “countryCode” field from the “address” object in the Profile Geo enrichment.
Uses a normalized set of two-letter country codes, based on ISO-3166-1-alpha-2 specification. This operator is provided in lieu of an operator for “country” field from the “address” object to be concise.| -|profile_region:|Matches on the “region” field from the “address” object in the Profile Geo enrichment.

This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation.| -|profile_locality:|Matches on the “locality” field from the “address” object in the Profile Geo enrichment.

This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation.| - - - **NOTE:** All is: and has: operators cannot be used as standalone operators when using the Search API, and must be combined with another clause. - -For example, @XDeevelopers has:links - - -| | | -| :--- | :--- | -| has:geo | Matches Posts that have Post-specific geo location data provided from X. This can be either “geo” lat-long coordinate, or a “location” in the form of a X [“Place”](https://dev.x.com/overview/api/places), with corresponding display name, geo polygon, and other fields.



**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:profile_geo | _Available alias_: has:derived\_user\_geo

Matches Posts that have any [Profile Geo](http://support.gnip.com/enrichments/profile_geo.html) metadata, regardless of the actual value.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:links | This operators matches Posts which contain links in the message body.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| is:retweet | Deliver only explicit retweets that match a rule. Can also be negated to exclude retweets that match a rule from delivery and only original content is delivered.

This operator looks only for true Retweets, which use X's retweet functionality. Quoted Tweets and Modified Posst which do not use X's retweet functionality will not be matched by this operator.



**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| is:reply | An operator to filter Posts based on whether they are or are not replies to Posts. Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a rule from delivery.

Note that this operator is available for paid premium and enterprise search and is not available in Sandbox dev environments.



**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| is:quote | Delivers only Quote Tweets, or Posts that reference another Post, as identified by the "is\_quote\_status":true in Post payloads. Can also be negated to exclude Quote Tweets.

**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| is:verified | Deliver only Posts where the author is “verified” by X. Can also be negated to exclude Posts where the author is verified.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:mentions | Matches Posts that mention another X user.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:hashtags | Matches Posts that contain a hashtag.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:media | _Available alias_: has:media_link

Matches Posts that contain a media url classified by X. For example, pic.x.com.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:images | Matches Posts that contain a media url classified by X. For example, pic.x.com.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:videos | _Available alias_: has:video_link

Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Vine, Periscope, or Posts with links to other video hosting sites.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | -| has:symbols | Matches Posts that contain a cashtag symbol (with a leading ‘$’ character. For example, $tag).  Note that this operator is only available in the `enterprise` search APIs.


**Note:** When using the Search API, this operator must be used in conjunction with other operators that don't include `is:` or `has:`. | - -### Product overview - -The enterprise-tier Full-archive Search was launched in August 2015, and the premium-tier version was launched in February 2018. These search products enable customers to immediately access any publicly available Post. With Full-archive Search you submit a single query and receive a response in classic RESTful fashion. Full-archive Search implements (up to) 500-Posts-per-response pagination, and supports up to a 60-requests-per-minute (rpm) rate-limit for premium, 120 rpm for enterprise. Given these details, Full-archive Search can be used to rapidly retrieve Posts, and at large scale using concurrent requests. - -Unlike Historical PowerTrack, whose archive is based on a set of Post flat-files on disk, the Full-archive Search Post archive is much like an on-line database. As with all databases, it supports making queries on its contents. It also makes use of an _index_ to enable high-performance data retrieval. With Full-archive search endpoints, the querying language is made up of PowerTrack Operators, and these Operators each correspond to a Post JSON attribute that is indexed. - -Also, like Historical PowerTrack, there are Post attributes that are current to the time a query is made. For example, if you are using Search API to access a Post posted in 2010 today, the user's profile description, account 'home' location, display name, and Post metrics for Favorites and Retweet counts will be updated to today’s values and not what they were in 2010.  - -### Metadata timelines - -Below is a timeline of when Full-archive search endpoint Operators begin matching. In some cases Operator matching began well _after_ a ‘communication convention’ became commonplace on X. For example, @Replies emerged as a user convention in 2006, but did not become a _first-class object_ or _event_ with ‘supporting’ JSON until early 2007. Accordingly, matching on @Replies in 2006 requires an examination of the Post body, rather than relying on the `to:` and `in_reply_to_status_id:` PowerTrack Operators. - -The details provided here were generated using Full-Archive Search (a product of hundreds of searches). This timeline is not 100% complete or precise. If you identify another filtering/metadata “born on date” fundamental to your use-case, please let us know. - -Note that the underlying Search index is subject to being rebuilt. Accordingly, these timeline details are subject to change. - -#### 2006 - -* March 26 - `lang:`. An example of Post metadata being backfilled while generating the Search index. -* July 13 - `has:mentions` begins matching. -* October 6 - `has:symbols`. $cashtags (or symbols) for discussing stock symbols does not become common until early 2009. Until then most usages were probably slang (e.g., $slang). -* October 26 - `has:links` begins matching. -* November 23 - `has:hashtags` begins matching. - -#### 2007 - -* January 30 - First first-class @reply (in\_reply\_to\_user\_id), `reply_to_status_id:` begins matching. -* August 23 - Hashtags emerge as a common convention for organizing topics and conversations. First real use a week later. - -#### 2009 - -* May 15 - `is:retweet`. Note that this Operator starts matching with the ‘beta’ release of official Retweets and its “Via @’ pattern. During this beta period, the Post verb is ‘post’ and the original Post is not included in the payload. -* August 13 - Final version of official Retweets is released with “RT @” pattern, a verb set to ‘share’, and the ‘retweet_status’ attribute containing the original Post (thus approximately doubling the JSON payload size). - -#### 2010 - -* March 6 - `has:geo`, `bounding_box:` and `point_radius:` geo Operators begin matching. -* August 28 - `has:videos` (Until February 2015, this Operator matches on Posts with links to select video hosting sites such as youtube.com, vimeo.com, and vivo.com). - -#### 2011 - -* July 20 - `has:media` and `has:images` begin matching. Native photos officially announced August 9, 2010. - -#### 2014 - -* December 3 - (Approximately) _Some_ [Enhanced URL metadata](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments) with HTML title and description begins in payloads. Enhanced metadata more fully emerged in May 2016. - -#### 2015 - -* February 10 - `has:videos` matches on ‘native’ X videos. -* February 17 - `has:profile_geo`, `profile_country:`, `profile_region:`, `profile_locality:` [Profile Geo](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) Operators begin matching. -* February 17 - `place_country:` and `place:` Post geo Operators begin matching. - -#### 2016 - -* May 1 - [Enhanced URL metadata](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments) more fully available, and was officially announced as part of the [Gnip 2.0 launch in August 2016](https://blog.x.com/2016/gnip-2-is-here). No associated Operators for these metadata with Search APIs. - -#### 2017 - -* February 22 - Poll metadata become available in enriched native format. No associated Operators for these metadata. - -#### 2022 - -* September 27 - All Post objects created since this date have Edited Post metadata available. All Enterprise endpoints that provide Post objects were updated to provide this metadata starting on this date. The edit metadata provided includes edit_history and edit_controls objects. These metadata will not be returned for Posts that were created before September 27, 2022. Currently, there are no Enterprise Operators available that match these metadata.  To learn more about Edit Post metadata, check out the [Edit Posts fundamentals](/x-api/fundamentals/edit-posts) page. - -#### 2022 - -* September 29 - All Post objects created since this date have Edited Post metadata available. All Enterprise endpoints that provide Post objects were updated to provide this metadata starting on this date. The edit metadata provided includes edit_history and edit_controls objects. These metadata will not be returned for Posts that were created before September 27, 2022. Currently, there are no Enterprise Operators available matching these metadata.  To learn more about Edit Post metadata, check out the [Edit Posts fundamentals](/x-api/fundamentals/edit-posts) page. - -### Filtering tips - -Given all the above timeline information, it is clear that there are a lot of details to consider when writing Search APIs filters. There are two key things to consider: - -* Some metadata have ‘born-on’ dates so filters can result in _false negatives_. Such searches include Operators reliant on metadata that did not exist for all of part of the search period. For example, if you are searching for Posts with the `has:images` Operator, you will not have any matches for periods before July 2011. That is because that Operator matches on _native_ photos (attached to a Post using the X user-interface). For a more complete data set of photo-sharing Posts, filters for before July 2011 would need to contain rule clauses that match on common URLs for photo hosting. -* Some metadata has been backfilled with metadata from a time _after_ the X was posted. - -There are several attribute types that are commonly focused on when creating PowerTrack queries: - -* X Profiles -* Original or shared Posts -* Post language classification -* Geo-referencing Posts -* Shared links media - -Some of these have product-specific behavior while others have identical behavior. See below for more details. - -#### X Profiles - -The Search APIs serves historical Posts with the user profile data set as it is at the _time of retrieval_. If you request a Post from 2014, the user’s profile metadata will reflect how it exists at query-time. - -#### Original Posts and Retweets - -The PowerTrack `_is:retweet_` Operator enables users to either include or exclude Retweets. Users of this Operator need to have two strategies for Retweet matching (or not matching) for data before August 2009. Before August 2009, the Post message itself needs to be checked, using exact phrase matching, for matches on the “@RT ” pattern (Actually, if you are filtering on Retweets from between May-August 2009, the “Via @” pattern should be included). For periods after August 2009, the _is:retweet_ Operator is available. - -#### Post language classifications - -For filtering on a Post's language classification, X's historical products are quite different. When the Search archive was built, all Posts were backfilled with the X language classification. Therefore the lang: Operator is available for the entire Post archive. - -#### Geo-referencing Posts - -There are three primary ways to geo-reference Posts: - -* **Geographical references in Post message.** Matching on geographic references in the Post message, while often the most challenging method since it depends on local knowledge, is an option for the entire Post archive. [Here](https://x.com/biz/statuses/28311) is an example geo-referenced match from 2006 for the San Francisco area based on a ‘golden gate’ filter. - -* **Posts geo-tagged by the user.** With the search APIs the ability to start matching on Posts with some Geo Operators started in March 2010, and with others in February 2015: - - * March 6, 2010: `has:geo`, `bounding_box:` and `point_radius:` - * February 17, 2015: `place_country:` and `place:` -* **Account profile ‘home’ location set by the user.** Profile Geo Operators are available in both Historical PowerTrack and the Search APIs. With the Search APIs, these Profile Geo metadata is available starting in February 2015. For Posts posted before Profile Geo metadata became available, the `bio_location:` Operator is available which can be used to match on non-normalized user input. - - -#### Shared links and media - -In March 2012, the expanded URL enrichment was introduced. Before this time, the Post payloads included only the URL as provided by the user. So, if the user included a shortened URL it can be challenging to match on (expanded) URLs of interest. With the Search APIs, these metadata are available starting in March 2012. - -In July 2016, the enhanced URL enrichment was introduced. This enhanced version provides a web site’s HTML title and description in the Post payload, along with Operators for matching on those. These metadata begin emerging in December 2014. - -In September 2016 X introduced ‘native attachments’ where a trailing shared link is not counted against the 140 Post character limit. Both URL enrichments still apply to these shared links. - -Here are when related Search Operators begin matching: - -* 2006 October 26 - `has:links` -* 2011 July 20 - `has:images` and `has:media` -* 2011 August - `url:` with the [Expanded URLs enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments) As early as September 2006 `(url:"spotify.com" OR url:gnip OR url:microsoft OR url:google OR url:youtube)` matches http://x.com/Adam/statuses/16602, even though there is no urls\[\] metadata in twitter_entities and gnip objects. “youtube.com” is an example of message content that, without any urls\[\] metadata, matches url:youtube. -* 2015 February 10 - `has:videos` for native videos. Between 2010/08/28 and 2015/02/10, this Operator matches on Posts with links to select video hosting sites such as youtube.com, vimeo.com, and vivo.com. -* 2016 May 1 - `url_title:` and `url_description:`, based on the [Enhanced URLs enrichment](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments), generally available. First Enhanced URL metadata began appearing in December 2014. - -## Frequently asked questions(FAQ) - -### General Search Post API questions - - -There is a known difference between results provided by the counts endpoint and the data endpoint. You may see a discrepancy in your results because the counts endpoint is pre-compliance (meaning that it does not account for things like deleted Posts, scrub geo, etc.) whereas the data endpoint is compliant at the time of delivery and accounts for all compliance events. - - - -There are a few different reasons why this might have happened, including - -1. the Post you expected to see is from a protected account -2. because the data endpoint accounts for all compliance events (meaning that deleted Posts, scrubbed geos, etc. will not be included in the response). - - -This is likely due to a wrong usage of our premium rules & filtering. Please review our documentation [here](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering) and ensure you understand the restrictions around building rules. - - -Yes, there are, including: - -* [Tweepy](http://www.tweepy.org/) \- good for using the standard search/Posts product (Python) -* [X API](https://github.com/geduldig/TwitterAPI) \- good for using the standard Search Post APIs (Python) -* [Search Posts Python](https://github.com/xdevplatform/search-tweets-python) and [Search Posts Ruby](https://github.com/xdevplatform/search-tweets-ruby) \- two good tools that can be used for enterprise (and v2!) Search Post APIs - -All of the libraries that we directly support can be found on our xdevplatform GitHub page: [https://github.com/xdevplatform](https://github.com/xdevplatform). - -There are [other third-party libraries](/resources/fundamentals/authentication#oauth-1-0a-2) that may also be helpful; however, please note that some of these may not work with our premium and enterprise products. - - -Yes. Our data endpoint paginates at either the specified `maxResults` or after 30 days. - -For example, if you have 800 Posts in a given 30 day period, you will have to make two requests to pull the complete results; because the maximum number of Posts that can be returned per request is 500 (`maxResults`). And if you just have 400 Posts in month one, and then 100 Posts in month two, you will also have to use two requests to pull the full results; because pagination takes place after a period of 30 days even if the first request returns less than the specified `maxResults` Posts. - - -Posts are returned in reverse chronological order. For example, the first page of results will show the most recent Posts that match the query, pagination will continue until the results posted dates get to the `fromDate` initially requested. - - -Only the original Post will count for billing purposes. Any subsequent edits will be ignored and not contribute to your overall activity count.  - -`Enterprise` - - -Our enterprise solutions are customized with predictable pricing to meet the needs of your business. Please apply [here](/x-api/enterprise-gnip-2.0/enterprise-gnip) for more information. - - -* Please refer to our enterprise Search Post APIs documentation [here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#enterprise-search-apis) -* Useful information on rules and filering can be found [here](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#enterprise-operators) -* Useful information for using the data endpoint can be found [here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#data-endpoint) -* Useful information for using the counts endpoint can be found [here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#counts-endpoint) -* A list of available operators can be found [here](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators) - - - -Please get in touch with your Account Manager at X who will be able to help you with this. - - - -### Error troubleshooting guide - -**Code 404 - Not Found** - -1. Please ensure you are using the right parameters for each endpoint (e.g. the `buckets`field can only be used with the counts endpoint, not the data endpoint) -2. Please double check the `:product` `:account_name` and `:label` fields are correct. You can find your `:label` field in the GNIP Console (enterprise customers only). - -## API Reference - -### Enterprise search APIs - -There are two enterprise search APIs: - -* 30-Day Search API - provides Tweets posted with the last 30 days. -* Full-Archive Search API - provides Tweets from as early as 2006, starting with the first Tweet posted in March 2006. - -These search APIs share a common design and the documentation below applies to both. Note that for Tweets created starting September 29, 2022, Tweet objects will include Tweet edit metadata that describes its edit history. See the ["Edit Tweets"](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) fundamentals page for more details. - -Below you will find important details needed when integrating with the enterprise search APIs: - -* Methods for requesting Tweet data and counts -* Authentication -* Pagination -* API request parameters and example requests -* API response JSON payloads and example responses -* HTTP response codes - -The enterprise APIs provide low-latency, full-fidelity, query-based access to the Tweet archive. The only difference in the two APIs is the time frame you can search, either the previous 30 days or from as early as 2006. Time frames can be specified with minute granularity. Tweet data is served in reverse chronological order, starting with the most recent Tweet that matches your query. Tweets are available from the search API approximately 30 seconds after being published. - -#### Methods - -The base URI for enterprise search is `https://gnip-api.x.com/search/`. - -| Method | Description | -| :--- | :--- | -| [POST /search/:product/accounts/:account_name/:label](#SearchRequests) | Retrieve Tweets from the past 30 days that match the specified PowerTrack rule. | -| [POST /search/:product/accounts/:account_name/:label/counts](#CountRequests) | Retrieve the number of Tweets from the past 30 days that match the specified PowerTrack rule. | - -Where: - -* `:product` indicates the search endpoint you are making requests to, either `30day` or `fullarchive`. -* `:account_name` is the (case-sensitive) name associated with your account, as displayed at console.gnip.com -* `:label` is the (case-sensitive) label associated with your search endpoint, as displayed at console.gnip.com - -For example, if the TwitterDev account has the 30-Day search product with a label of 'prod' (short for production), the search endpoints would be: - -* Data endpoint: [https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod.json](https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod.json) -* Counts endpoint: [https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod/counts.json](https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod/counts.json) - -Your complete enterprise search API endpoint is displayed at [https://console.gnip.com](https://console.gnip.com). - -Below there are several example requests using a simple HTTP utility called curl. These examples use URLs with `:product`, `:account_name`, and `:label`. To use these examples, be sure to update the URLs with your details. - -#### Authentication - -All requests to the enterprise search APIs must use HTTP _Basic Authentication_, constructed from a valid email address and password combination used to log into your account at [https://console.gnip.com](https://console.gnip.com). Credentials must be passed as the _Authorization_ header for each request. - -#### Request/response behavior - -Using the `fromDate` and `toDate` parameters, you can request any time period that the API supports. The 30-Day search API provides Tweets from the most recent 31 days (even though referred to as the '30-Day' API, it makes 31 days available to enable users to make complete-month requests). The Full-Archive search API provides Tweets back to the very first tweet (March 21, 2006). However, a single response will be limited to the lesser of your specified 'maxResults' or 31 days. If matching data or your time range exceeds your specified maxResults or 31 days, you will receive a 'next' token which you should use to paginate through the remainder of your specified time range. - -For example, say you are using Full-Archive search and want all Tweets matching your query from January 1, 2017 to June 30, 2017. You will specify that full six-month time period in your request using the `fromDate` and `toDate` parameters. The search API will respond with the first 'page' of Tweets, with the number of Tweets matching your `maxResults` parameter (which defaults to 100). Assuming there are more Tweets (and there most likely will be more), the API will also provide a 'next' token that enables you to make a request for the next 'page' of data. This process is repeated until the API does not return a 'next' token. See the next section for more details. - -#### Pagination - -When making both data and count requests it is likely that there is more data than can be returned in a single response. When that is the case the response will include a ‘next’ token. The ‘next’ token is provided as a root-level JSON attribute. Whenever a ‘next’ token is provided, there is additional data to retrieve so you will need to keep making API requests. - -**Note:** The ‘next’ token behavior differs slightly for data and counts requests, and both are described below with example responses provided in the API Reference section. - -##### Data pagination - -Requests for data will likely generate more data than can be returned in a single response. Each data request includes a parameter that sets the maximum number of Tweets to return per request. This `maxResults` parameter defaults to 100 and can be set to a range of 10-500. If your query matches more Tweets than the 'maxResults' parameter used in the request, the response will include a 'next' token (as a root-level JSON attribute). This 'next' token is used in the subsequent request to retrieve the next portion of the matching Tweets for that query (i.e. the next 'page”). Next tokens will continue to be provided until you have reached the last 'page' of results for that query when no 'next' token is provided. - -To request the next 'page' of data, you must make the exact same query as the original, including `query`, `toDate`, and `fromDate` parameters, if used, and also include a 'next' request parameter set to the value from the previous response. This can be utilized with either a GET or POST request. However, the 'next' parameter must be URL encoded in the case of a GET request. - -You can continue to pass in the 'next' element from your previous query until you have received all Tweets from the time period covered by your query. When you receive a response that does not include a 'next' element, it means that you have reached the last page and no additional data is available for the specified query and time range. - -##### Counts pagination - -The 'counts' endpoint provides Tweet volumes associated with a query on either a daily, hourly, or per-minute basis. The 'counts' API endpoint will return a timestamped array of counts for a maximum of a 31-day payload of counts. If you request more than 31 days of counts you will be provided a 'next' token. As with the data 'next' tokens, you must make the exact same query as the original and also include a 'next' request parameter set to the value from the previous response. - -Beyond requesting more than 31 days of counts, there is another scenario when a 'next' token is provided. For higher volume queries, there is the potential that the generation of counts will take long enough to trigger a response timeout. When this occurs you will receive less than 31 days of counts but will be provided a 'next' token in order to continue making requests for the entire payload of counts. **_Important:_** Timeouts will only issue full "buckets" - so 2.5 days would result in 2 full day "buckets". - -##### Additional notes - -* When using a fromDate or toDate in a search request, you will only get results from within your time range. When you reach the last group of results within your time range, you will not receive a 'next' token. -* The 'next' element can be used with any maxResults value between 10-500 (with a default value of 100). The maxResults determines how many Tweets are returned in each response, but does not prevent you from eventually getting all results. -* The 'next' element does not expire. Multiple requests using the same 'next' query will receive the same results, regardless of when the request is made. -* When paging through results using the 'next' parameter, you may encounter duplicates at the edges of the query. Your application should be tolerant of these. - -#### Data endpoint - -##### POST /search/:product/:label - -###### Endpoint pattern: - -This endpoint returns data for the specified query and time period. If a time period is not specified the time parameters will default to the last 30 days. Note: This functionality can also be accomplished using a GET request, instead of a POST, by encoding the parameters described below into the URL. - -##### Data request parameters - -| Parameters | Description | Required | Sample Value | -| :--- | :--- | :--- | :--- | -| query | The equivalent of one PowerTrack rule, with up to 2,048 characters (and no limits on the number of positive and negative clauses).

This parameter should include ALL portions of the PowerTrack rule, including all operators, and portions of the rule should not be separated into other parameters of the query.

**Note:** Not all PowerTrack operators are supported. Supported Operators are listed [HERE](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators). | Yes | (snow OR cold OR blizzard) weather | -| tag | Tags can be used to segregate rules and their matching data into different logical groups. If a rule tag is provided the rule tag is included in the 'matching_rules' attribute.

It is recommended to assign rule-specific UUIDs to rule tags and maintain desired mappings on the client side. | No | 8HYG54ZGTU | -| fromDate | The oldest UTC timestamp (back to 3/21/2006 with Full-Archive search) from which the Tweets will be provided. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute).

_Specified:_ Using only the fromDate with no toDate parameter will deliver results for the query going back in time from now( ) until the fromDate.

_Not Specified:_ If a fromDate is not specified, the API will deliver all of the results for 30 days prior to now( ) or the toDate (if specified).

If neither the fromDate or toDate parameter is used, the API will deliver all results for the most recent 30 days, starting at the time of the request, going backwards. | No | 201207220000 | -| toDate | The latest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in minute granularity and is not inclusive (i.e. 11:59 does not include the 59th minute of the hour).

_Specified:_ Using only the toDate with no fromDate parameter will deliver the most recent 30 days of data prior to the toDate.

_Not Specified:_ If a toDate is not specified, the API will deliver all of the results from now( ) for the query going back in time to the fromDate.

If neither the fromDate or toDate parameter is used, the API will deliver all results for the entire 30-day index, starting at the time of the request, going backwards. | No | 201208220000 | -| maxResults | The maximum number of search results to be returned by a request. A number between 10 and the system limit (currently 500). By default, a request response will return 100 results. | No | 500 | -| next | This parameter is used to get the next 'page' of results as described [HERE](#Pagination). The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. | No | NTcxODIyMDMyODMwMjU1MTA0 | - - - -###### Additional details - -| | | -| :--- | :--- | -| **Available Timeframe** | 30-Day: last 31 days
Full-Archive: March 21, 2006 - Present | -| **Query Format** | The equivalent of one PowerTrack rule, with up to 2,048 characters (and no limits on the number of positive and negative clauses).

**Note:** Not all PowerTrack operators are supported. Refer to [Available operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators) for a list of supported operators. | -| **Rate Limit** | Partners will be rate limited at both minute and second granularity. The per minute rate limit will vary by partner as specified in your contract. However, these per-minute rate limits are not intended to be used in a single burst. Regardless of your per minute rate limit, all partners will be limited to a maximum of 20 requests per second, aggregated across all requests for data and/or counts. | -| **Compliance** | All data delivered via the Full-Archive Search API is compliant at the time of delivery. | -| **Realtime Availability** | Data is available in the index within 30 seconds of generation on the Twitter Platform | - -##### Example data requests and responses - -###### Example POST request - -* Request parameters in a POST request are sent via a JSON-formatted body, as shown below. -* All portions of the PowerTrack rule being queried for (e.g. keywords, other operators like bounding_box:) should be placed in the 'query' parameter. -* Do not split portions of the rule out as separate parameters in the query URL. - -Here is an example POST (using cURL) command for making an initial data request: -```bash - curl -X POST -u "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm"}' -``` -If the API data response includes a 'next' token, below is a subsequent request that consists of the original request, with the 'next' parameter set to the provided token: -```bash - curl -X POST -u "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm", - "next":"NTcxODIyMDMyODMwMjU1MTA0"}' -``` -###### Example GET request - -* Request parameters in a GET request are encoded into the URL, using standard URL encoding. -* All portions of the PowerTrack rule being queried for (e.g. keywords, other operators like bounding_box:) should be placed in the 'query' parameter. -* Do not split portions of the rule out as separate parameters in the query URL. - -Here is an example GET (using cURL) command for making an initial data request: -```bash - curl -u "http://gnip-api.x.com/search/:product/accounts/:account_name/:label.json?query=from%3Atwitterdev&maxResults=500&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm" -``` -###### Example data responses - -Note that for Tweets created starting September 29, 2022, Tweet objects will include Tweet edit metadata that describes its edit history. See the ["Edit Tweets"](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) fundamentals page for more details. - -Below is an example response to a data query. This example assumes that there were more than ‘maxResults’ Tweets available so a 'next' token is provided for subsequent requests. If 'maxResults' or fewer Tweets are associated with your query, no 'next' token would be included in the response. -The value of the 'next' element will change with each query and should be treated as an opaque string. The 'next' element will look like the following in the response body: -```json -{ - "results": - [ - {--Tweet 1--}, - {--Tweet 2--}, - ... - {--Tweet 500--} - ], - "next":"NTcxODIyMDMyODMwMjU1MTA0", - "requestParameters": - { - "maxResults":500, - "fromDate":"201101010000", - "toDate":"201201010000" - } - } -``` -The response to a subsequent request might look like the following (note the new Tweets and different 'next' value): -```json -{ - "results": - [ - {--Tweet 501--}, - {--Tweet 502--}, - ... - {--Tweet 1000--} - ], - "next":"R2hCDbpBFR6eLXGwiRF1cQ", - "requestParameters": - { - "maxResults":500, - "fromDate":"201101010000", - "toDate":"201201010000" - } - } -``` -You can continue to pass in the 'next' element from your previous query until you have received all Tweets from the time period covered by your query. When you receive a response that does not include a 'next' element, it means that you have reached the last page and no additional data is available in your time range. - - -#### Counts endpoint - -##### /search/:stream/counts - -###### Endpoint pattern: - -`/search/fullarchive/accounts/:account_name/:label/counts.json` - -This endpoint returns counts (data volumes) data for the specified query. If a time period is not specified the time parameters will default to the last 30 days. Data volumes are returned as a timestamped array on either daily, hourly (default), or by the minute. - -**Note:** This functionality can also be accomplished using a GET request, instead of a POST, by encoding the parameters described below into the URL. - -##### Counts request parameters - -| Parameters | Description | Required | Sample Value | -| :--- | :--- | :--- | :--- | -| query | The equivalent of one PowerTrack rule, with up to 2,048 characters (and no limits on the number of positive and negative clauses).

This parameter should include ALL portions of the PowerTrack rule, including all operators, and portions of the rule should not be separated into other parameters of the query.

**Note:** Not all PowerTrack operators are supported. Refer to [Available operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators) for a list of supported operators. | Yes | (snow OR cold OR blizzard) weather | -| fromDate | The oldest UTC timestamp (back to 3/21/2006) from which the Tweets will be provided. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute).

_Specified:_ Using only the fromDate with no toDate parameter, the API will deliver counts (data volumes) data for the query going back in time from now until the fromDate. If the fromDate is older than 31 days from now( ), you will receive a next token to page through your request.

_Not Specified:_ If a fromDate is not specified, the API will deliver counts (data volumes) for 30 days prior to now( ) or the toDate (if specified).

If neither the fromDate or toDate parameter is used, the API will deliver counts (data volumes) for the most recent 30 days, starting at the time of the request, going backwards. | No | 201207220000 | -| toDate | The latest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in minute granularity and is not inclusive (i.e. 11:59 does not include the 59th minute of the hour).

_Specified:_ Using only the toDate with no fromDate parameter will deliver the most recent counts (data volumes) for 30 days prior to the toDate.

_Not Specified:_ If a toDate is not specified, the API will deliver counts (data volumes) for the query going back in time to the fromDate. If the fromDate is more than 31 days from now( ), you will receive a next token to page through your request.

If neither the fromDate or toDate parameter is used, the API will deliver counts (data volumes) for the most recent 30 days, starting at the time of the request, going backwards. | No | 201208220000 | -| bucket | The unit of time for which count data will be provided. Count data can be returned for every day, hour or minute in the requested timeframe. By default, hourly counts will be provided. Options: 'day', 'hour', 'minute' | No | minute | -| next | This parameter is used to get the next 'page' of results as described [HERE](#Pagination). The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. | No | NTcxODIyMDMyODMwMjU1MTA0 | - -###### Additional details - -| | | -| :--- | :--- | -| **Available Timeframe** | 30-Day: last 31 days
Full-Archive: March 21, 2006 - Present | -| **Query Format** | The equivalent of one PowerTrack rule, with up to 2,048 characters.

**Note:** Not all PowerTrack operators are supported. Refer to [Available operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#available-operators) for a list of supported operators. | -| **Rate Limit** | Partners will be rate limited at both minute and second granularity. The per minute rate limit will vary by partner as specified in your contract. However, these per-minute rate limits are not intended to be used in a single burst. Regardless of your per minute rate limit, all partners will be limited to a maximum of 20 requests per second, aggregated across all requests for data and/or counts. | -| **Count Precision** | The counts delivered through this endpoint reflect the number of Tweets that occurred and do not reflect any later compliance events (deletions, scrub geos). Some Tweets counted may not be available via data endpoint due to user compliance actions. | - -##### Example counts requests and responses - -###### Example POST request - -* Request parameters in a POST request are sent via a JSON-formatted body, as shown below. -* All portions of the PowerTrack rule being queried for (e.g. keywords, other operators like bounding_box:) should be placed in the 'query' parameter. -* Do not split portions of the rule out as separate parameters in the query URL. - -Here is an example POST (using cURL) command for making an initial counts request: -```bash - curl -X POST -u "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day"}' -``` -If the API counts response includes a 'next' token, below is a subsequent request that consists of the original request, with the 'next' parameter set to the provided token: -```bash - curl -X POST -u "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day", - "next":"YUcxO87yMDMyODMwMjU1MTA0"}' -``` - -###### Example GET request - -* Request parameters in a GET request are encoded into the URL, using standard URL encoding -* All portions of the PowerTrack rule being queried for (e.g. keywords, other operators like bounding_box:) should be placed in the 'query' parameter -* Do not split portions of the rule out as separate parameters in the query URL - -Here is an example GET (using cURL) command for making an initial counts request: -```bash - curl -u "http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label/counts.json?query=TwitterDev&bucket=day&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm" -``` -#### Example counts responses - -Below is an example response to a counts (data volume) query. This example response includes a 'next' token, meaning the counts request was for more than 31 days, or that the submitted query had a large enough volume associated with it to trigger a partial response. - -The value of the 'next' element will change with each query and should be treated as an opaque string. The 'next' element will look like the following in the response body: -```json - { - "results": [ - { "timePeriod": "201101010000", "count": 32 }, - { "timePeriod": "201101020000", "count": 45 }, - { "timePeriod": "201101030000", "count": 57 }, - { "timePeriod": "201101040000", "count": 123 }, - { "timePeriod": "201101050000", "count": 134 }, - { "timePeriod": "201101060000", "count": 120 }, - { "timePeriod": "201101070000", "count": 43 }, - { "timePeriod": "201101080000", "count": 65 }, - { "timePeriod": "201101090000", "count": 85 }, - { "timePeriod": "201101100000", "count": 32 }, - { "timePeriod": "201101110000", "count": 23 }, - { "timePeriod": "201101120000", "count": 85 }, - { "timePeriod": "201101130000", "count": 32 }, - { "timePeriod": "201101140000", "count": 95 }, - { "timePeriod": "201101150000", "count": 109 }, - { "timePeriod": "201101160000", "count": 34 }, - { "timePeriod": "201101170000", "count": 74 }, - { "timePeriod": "201101180000", "count": 24 }, - { "timePeriod": "201101190000", "count": 90 }, - { "timePeriod": "201101200000", "count": 85 }, - { "timePeriod": "201101210000", "count": 93 }, - { "timePeriod": "201101220000", "count": 48 }, - { "timePeriod": "201101230000", "count": 37 }, - { "timePeriod": "201101240000", "count": 54 }, - { "timePeriod": "201101250000", "count": 52 }, - { "timePeriod": "201101260000", "count": 84 }, - { "timePeriod": "201101270000", "count": 120 }, - { "timePeriod": "201101280000", "count": 34 }, - { "timePeriod": "201101290000", "count": 83 }, - { "timePeriod": "201101300000", "count": 23 }, - { "timePeriod": "201101310000", "count": 12 } - ], - "totalCount":2027, - "next":"NTcxODIyMDMyODMwMjU1MTA0", - "requestParameters": - { - "bucket":"day", - "fromDate":"201101010000", - "toDate":"201201010000" - } - } -``` -The response to a subsequent request might look like the following (note the new counts timeline and different 'next' value): -```json - { - "results": [ - { "timePeriod": "201102010000", "count": 45 }, - { "timePeriod": "201102020000", "count": 76 }, - .... - { "timePeriod": "201103030000", "count": 13 } - ], - "totalCount":3288, - "next":"WE79fnakFanyMDMyODMwMjU1MTA0", - "requestParameters": - { - "bucket":"day", - "fromDate":"201101010000", - "toDate":"201201010000" - } - } -``` - -You can continue to pass in the 'next' element from your previous query until you have received all counts from the query time period. When you receive a response that does not include a 'next' element, it means that you have reached the last page and no additional counts are available in your time range. - -#### HTTP response codes - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful. The JSON response will be similar to the following: | -| 400 | Bad Request | Generally, this response occurs due to the presence of invalid JSON in the request, or where the request failed to send any JSON payload. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 404 | Not Found | The resource was not found at the URL to which the request was sent, likely because an incorrect URL was used. | -| 422 | Unprocessable Entity | This is returned due to invalid parameters in the query -- e.g. invalid PowerTrack rules. | -| 429 | Unknown Code | Your app has exceeded the limit on connection requests. The corresponding JSON message will look similar to the following: | -| 500 | Internal Server Error | There was an error on the server side. Retry your request using an exponential backoff pattern. | -| 502 | Proxy Error | There was an error on server side. Retry your request using an exponential backoff pattern. | -| 503 | Service Unavailable | There was an error on server side. Retry your request using an exponential backoff pattern. | +The Posts you get back in your payload can be in a data format, which provides you with the full Post payload, or it can be in a counts format which gives you numerical count data of matched Posts. We will be u \ No newline at end of file diff --git a/x-api/enterprise-gnip-2.0/powertrack-api.mdx b/x-api/enterprise-gnip-2.0/powertrack-api.mdx index f7fade9b3..5e3a61726 100644 --- a/x-api/enterprise-gnip-2.0/powertrack-api.mdx +++ b/x-api/enterprise-gnip-2.0/powertrack-api.mdx @@ -1,7 +1,8 @@ --- title: PowerTrack API keywords: ["PowerTrack", "PowerTrack API", "enterprise PowerTrack", "GNIP PowerTrack", "streaming API", "enterprise streaming"] ---- + +description: This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the ["Edit Posts" fundamentals page](/x-api/enterprise-...--- This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the ["Edit Posts" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets).  ## Overview @@ -269,1714 +270,4 @@ As described, customers add filtering rules to the PowerTrack stream to determin The set of PowerTrack rules used to filter a customer’s stream is highly flexible. If a customer needs to add a new filtering rule to capture a different type of content, or remove an existing rule, their app can send a request to the PowerTrack API to make it happen. When that request is sent, the filtering rules are automatically modified and the changes simply take effect in the data stream with no need to reconnect. This allows customers to provide data for many customers at scale, while supporting distinct filtering requirements for each of those customers. -[See Complete List of Operators »](/x-api/enterprise-gnip-2.0/powertrack-api#available-operators) - -#### Data - -Data is delivered to the customer’s app through a constant stream as it is created. The realtime stream does not provide recent data – rather, it begins filtering for and delivering results based on the time a filtering rule is added to the stream. If, in addition to realtime data, your product also requires instant access to recent data, we recommend using the [Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api). - -Data is in Gzip compressed JSON format. - -#### Matching Rules - -When an activity is delivered through the PowerTrack stream, adds metadata in the [“matching rules”](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#matching-rules) portion of that activity to indicate which rule or rules caused that specific activity to be delivered. If multiple rules match a single activity, the activity is delivered a single time with each of the matching rules included in this metadata. The matching rules provide an easy way to associate a specific activity with specific rules and customers in your product, even where you have many customers with lots of distinct rules. Since the data is delivered through a single stream in this manner, scaling up as your product gains additional customers is simple. - -#### Rule Tags - -At the time they are created, each filtering rule may be created with a tag. Rule tags have no special meaning, they are simply treated as opaque strings carried along with the rule. They will be included in the “matching rules” metadata in activities returned. Tags provide an easy way to create logical groupings of PowerTrack rules. For example, you may generate a unique ID for a specific rule as its tag, and allow your app to reference that ID within activities it processes to associate a result with specific customers, campaigns, categories, or other related groups. - -Note that tags cannot be updated on an existing rule, but can only be included when a rule is created. In order to “update” a tag, you need to first remove the rule, then add it again with the updated tag. The best solution is to simply use a unique identifier as your tag, which your system can associate with various other data points within your own app, all without having to change anything in the rule set. - -PowerTrack API - -### PowerTrack operators - -Below is a list of all operators supported in X's enterprise real-time and historical PowerTrack APIs. - - OperatorDescriptionkeyword -Matches a keyword within the body of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (for example, coca-cola), symbol, or separator characters, you must use a quoted exact match as described below. - -**Note:** This operator will match on both URLs and unwound URLs within a Post.emoji -Matches an emoji within the body of a Post. Emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Post with the text “I like 🍕” would be split into the following tokens: I, like, 🍕. These tokens would then be compared to the emoji used in your rule. Note that if an emoji has a variant, you must use “quotations” to add to a rule. -"exact phrase match" - -Matches an exact phrase within the body of a Post. - -**Note:** In 30 Day Search and Full Archive Search, punctuation is not tokenized and is instead treated as whitespace.  -For example, quoted “#hashtag” will match “hashtag” but not #hashtag (use the hashtag # operator without quotes to match on actual hashtags  -For example, quoted “$cashtag” will match “cashtag” but not $cashtag (use the cashtag $ operator without quotes to match on actual cashtags - -**Note:** This operator will match on both URLs and unwound URLs within a Post. - -# - -Matches any Post with the given hashtag. - -This operator performs an exact match, NOT a tokenized match, meaning the rule “2016” will match posts with the exact hashtag “2016”, but not those with the hashtag “2016election” - -Note: that the hashtag operator relies on X's entity extraction to match hashtags, rather than extracting the hashtag from the body itself. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-entities) for more information on X Entities JSON attributes. - -@ - -Matches any Post that mentions the given username. - -The to: operator returns a subset match of the @mention operator. - -"keyword1 keyword2"~N - -Commonly referred to as a proximity operator, this matches a Post where the keywords are no more than N tokens from each other. - -If the keywords are in the opposite order, they can not be more than N-2 tokens from each other. - -Can have any number of keywords in quotes. - -N cannot be greater than 6. - -**Example:** ********************"snowy mountain resort"~6******************** - -contains: - -Substring match for Posts that have the given substring in the body, regardless of tokenization. In other words, this does a pure substring match and does not consider word boundaries. - -Use double quotes to match substrings that contain whitespace or punctuation. - -from: - -Matches any Post from a specific user. - -The value must be the user’s X numeric Account ID or username (excluding the @ character). See HERE or [HERE](http://gettwitterid.com/) for methods for looking up numeric X Account IDs. - -url: -Performs a tokenized (keyword/phrase) match on the expanded URLs of a Post (similar to url_contains). Tokens and phrases containing punctuation or special characters should be double-quoted. For example, url:"/developer". While generally not recommended, if you want to match on a specific protocol, enclose in double-quotes: url:"https://developer.x.com". - -**Note:** When using PowerTrack or Historical PowerTrack, this operator will match on URLs contained within the original Post of a Quote Tweet. For example, if your rule includes url:"developer.x.com", and a Post contains that URL, any Quote Tweets of that POst will be included in the results. This is not the case when using the Search API.url_title: - -_Available alias_: url_title: - -Performs a keyword/phrase match on the (new) expanded URL HTML title metadata. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#expanded-and-enhanced-urls) for more information on expanded URL enrichment. - -url_description: - -_Available alias_: within\_url\_description: - -Performs a keyword/phrase match on the (new) expanded page description metadata. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#expanded-and-enhanced-urls) for more information on expanded URL enrichment. - -url_contains: - -Matches Posts with URLs that literally contain the given phrase or keyword. To search for patterns with punctuation in them (i.e. google.com) enclose the search term in quotes. - -NOTE: If you’re using the [Expanded URL](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#expanded-and-enhanced-urls) output format, we will match against the expanded URL as well. - -bio: - -_Available alias_: user_bio: - -Matches a keyword or phrase within the user bio of a Post. This is a tokenized match within the contents of the 'description' field within the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object). - -bio_name: -Matches a keyword within the user bio name of a Post. This is a tokenized match within the contents of a user’s “name” field within the [User object](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-user-object). -bio_location: - -_Available alias_: user\_bio\_location:  - -Matches posts where the User object's location contains the specified keyword or phrase. This operator performs a tokenized match, similar to the normal keyword rules on the message body. - -This location is part of the [User object](https://developer.x.com/en/docs/x-api/v1/data-dictionary/native-enriched-objects/user), and is the account's 'home' location, is a non-normalized, user-generated, free-form string, and is different from a Post's location (when available).  - -statuses_count: - -_Available alias_: tweets_count: - -Matches Posts when the author has posted a number of statuses that falls within the given range. - -If a single number is specified, any number equal to or higher will match. - -Additionally, a range can be specified to match any number in the given range  (for example, statuses_count:1000..10000). - -followers_count: - -Matches Posts when the author has a followers count within the given range. - -If a single number is specified, any number equal to or higher will match. - -Additionally, a range can be specified to match any number in the given range (for example, followers_count:1000..10000). - -friends_count: - -_Available alias_: following_count:  - -Matches Posts when the author has a friends count (the number of users they follow) that falls within the given range. - -If a single number is specified, any number equal to or higher will match. - -Additionally, a range can be specified to match any number in the given range (for example, friends_count:1000..10000). - -listed_count: - -_Available alias_: user\_in\_lists_count:  - -Matches Posts when the author has been listed on X a number of times falls within the given range. - -If a single number is specified, any number equal to or higher will match. - -Additionally, a range can be specified to match any number in the given range (for example, listed_count:10..100). - -$ - -Matches any Post that contains the specified ‘cashtag’ (where the leading character of the token is the ‘$’ character). - -Note that the cashtag operator relies on X's ‘symbols’ entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself. See [HERE](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#x-entities) for more information on X Entities JSON attributes. - -retweets_of: - -_Available alias_: retweets\_of\_user: - -Matches Posts that are Retweets of a specified user. Accepts both usernames and numeric X Account IDs (NOT Post status IDs). -See [HERE](/x-api/users/lookup/introduction) for methods for looking up numeric X Account IDs. - -retweets\_of\_status_id: - -_Available alias_: retweets\_of\_tweet_id:  - -Deliver only explicit Retweets of the specified Post. Note that the status ID used should be the ID of an original Post and not a Retweet.  - -in\_reply\_to\_status\_id: - -_Available alias_: in\_reply\_to\_tweet\_id: - -Deliver only explicit replies to the specified Post. - -sample: - -Returns a random sample of Posts that match a rule rather than the entire set of Posts. Sample percent must be represented by an integer value between 1 and 100. This operator applies to the entire rule and requires any “OR’d” terms be grouped. - -**Important Note:** The sample operator first reduces the scope of the firehose to X%, then the rule/filter is applied to that sampled subset. If you are using, for example, **sample:10**, each Post has a 10% chance of being in the sample.  - -Also, the sampling is deterministic, and you will get the same data sample in realtime as you would if you pulled the data historically. - -source:Matches any Post generated by the given source application. The value must be either the name of the application or the application’s URL. **Cannot be used alone.** -lang: - -Matches Posts that have been classified by X as being of a particular language (if, and only if, the post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results. - -**Note:** if no language classification can be made the provided result is ‘und’ (for undefined). - -The list below represents the currently supported languages and their corresponding BCP 47 language identifier: - -| | | | | -| :--- | :--- | :--- | :--- | -| Amharic: am | German: de | Malayalam: ml | Slovak: sk | -| Arabic: ar | Greek: el | Maldivian: dv | Slovenian: sl | -| Armenian: hy | Gujarati: gu | Marathi: mr | Sorani Kurdish: ckb | -| Basque: eu | Haitian Creole: ht | Nepali: ne | Spanish: es | -| Bengali: bn | Hebrew: iw | Norwegian: no | Swedish: sv | -| Bosnian: bs | Hindi: hi | Oriya: or | Tagalog: tl | -| Bulgarian: bg | Latinized Hindi: hi-Latn | Panjabi: pa | Tamil: ta | -| Burmese: my | Hungarian: hu | Pashto: ps | Telugu: te | -| Croatian: hr | Icelandic: is | Persian: fa | Thai: th | -| Catalan: ca | Indonesian: in | Polish: pl | Tibetan: bo | -| Czech: cs | Italian: it | Portuguese: pt | Traditional Chinese: zh-TW | -| Danish: da | Japanese: ja | Romanian: ro | Turkish: tr | -| Dutch: nl | Kannada: kn | Russian: ru | Ukrainian: uk | -| English: en | Khmer: km | Serbian: sr | Urdu: ur | -| Estonian: et | Korean: ko | Simplified Chinese: zh-CN | Uyghur: ug | -| Finnish: fi | Lao: lo | Sindhi: sd | Vietnamese: vi | -| French: fr | Latvian: lv | Sinhala: si | Welsh: cy | -| Georgian: ka | Lithuanian: lt | | - -place: - -Matches Posts tagged with the specified location _or_ X place ID (see examples). Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes. - -**Note:** See the [GET geo/search](https://developer.x.com/en/docs/x-api/v1/geo/places-near-location/api-reference/get-geo-search) public API endpoint for how to obtain X place IDs. - -**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. - -place_country: - -Matches Posts where the country code associated with a tagged [place/location](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-geo-objects) matches the given ISO alpha-2 character code. - -Valid ISO codes can be found here: [http://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - -**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. - -point_radius:\[lon lat radius\] - -Matches against the Exact Location (x,y) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region. - -* Units of radius supported are miles (mi) and kilometers (km). -* Radius must be less than 25mi. -* Longitude is in the range of ±180 -* Latitude is in the range of ±90 -* All coordinates are in decimal degrees. -* Rule arguments are contained within brackets, space delimited. - -**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. - -**Example:** ********************point\_radius:\[2.355128 48.861118 16km\] OR point\_radius:\[-41.287336 174.761070 20mi\]******************** - -bounding\_box:\[west\_long south\_lat east\_long north_lat\] - -_Available alias_: geo\_bounding\_box: - -Matches against the Exact Location (long, lat) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region. - -* west\_long south\_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude. -* east\_long and north\_lat represent the northeast corner of the bounding box, where east\_long is the longitude of that point, and north\_lat is the latitude. -* Width and height of the bounding box must be less than 25mi -* Longitude is in the range of ±180 -* Latitude is in the range of ±90 -* All coordinates are in decimal degrees. -* Rule arguments are contained within brackets, space delimited. - -**Note:** This operator will not match on Retweets, since Retweet's places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. - -**Example:** ********************bounding_box:\[-105.301758 39.964069 -105.178505 40.09455\]******************** - -profile_country: - -Exact match on the “countryCode” field from the “address” object in the Profile Geo enrichment. - -Uses a normalized set of two-letter country codes, based on ISO-3166-1-alpha-2 specification. This operator is provided in lieu of an operator for “country” field from the “address” object to be concise. - -profile_region: - -Matches on the “region” field from the “address” object in the Profile Geo enrichment. - -This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation. - -profile_locality: - -Matches on the “locality” field from the “address” object in the Profile Geo enrichment. - -This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation. - -profile_subregion: - -Matches on the “subRegion” field from the “address” object in the [Profile Geo](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) enrichment. In addition to targeting specific counties, these operators can be helpful to filter on a metro area without defining filters for every city and town within the region. - -This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\\/two”. Use double quotes to match substrings that contain whitespace or punctuation. - -has:geo - -Matches Posts that have Post-specific geolocation data provided from X. This can be either “geo” lat-long coordinate, or a “location” in the form of a X [“Place”](https://dev.x.com/overview/api/places), with the corresponding display name, geo polygon, and other fields. - -**Note:** Operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. - -has:profile_geo - -_Available alias_: has:derived\_user\_geo - -Matches Posts that have any [Profile Geo](/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments#profile-geo) metadata, regardless of the actual value. - -has:links - -This operator matches Posts which contain links in the message body.is:retweet - -Deliver only explicit retweets that match a rule. Can also be negated to exclude retweets that match a rule from delivery and only original content is delivered. - -This operator looks only for true Retweets, which use X's Retweet functionality. Quoted Tweets and Modified Posts which do not use X's Retweet functionality will not be matched by this operator. - -Can also be negated to match only on original Posts. - -is:quoteDelivers only Quote Tweets, or Posts that reference another Post, as identified by the "is\_quote\_status":true in POst payloads. Can also be negated to exclude Quote Tweets. -is:verified -Deliver only Posts where the author is “verified” by X. Can also be negated to exclude Posts where the author is verified. -is:replyDeliver only replies that match a rule. It can also be negated to exclude delivery of replies that match the specified rule. This operator matches on replies in original Posts, as well as replies in quoted Tweets and Retweets. You can use is:reply in conjunction with is:retweet and is:quote to only deliver replies to original Posts. --is:nullcast - -Negation only. Negates Posts that are nullcasted (for example, contains the ********************"scopes": \{"followers": false}"******************** object). For more info on Nullcasted Posts, [see here](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/guides/tweet-availability). - -Note: Must be used at highest level of rule when used with the Search API.  -Example: (gold AND silver) -is:nullcast - -has:mentions -Matches Posts that mention another X user. -has:hashtags -Matches Posts that contain a hashtag. -has:media - -_Available alias_: has:media_link - -Matches Posts that contain a media URL classified by X. For example, pic.x.com. - -has:images -Matches Posts that contain a media URL classified by X. For example, pic.x.com. -has:videos - -_Available alias_: has:video_link - -Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Vine, Periscope, or Posts with links to other video hosting sites. - -has:symbols -Matches Posts that contain a cashtag symbol (with a leading ‘$’ character. For example, $tag). - - -### Connecting to a streaming endpoint - -Establishing a connection to the streaming APIs means making a very long lived HTTP request, and parsing the response incrementally. Conceptually, you can think of it as downloading an infinitely long file over HTTP. - -**Authentication** - -The following authentication methods are supported by the Streaming APIs: - -| | | | -| :--- | :--- | :--- | -| Auth Type | Supported APIs | Description | -| [OAuth](/resources/fundamentals/authentication) | * Track API Stream | Requests must be authorized [according to the OAuth specification](/resources/fundamentals/authentication) . | -| [Basic auth](/resources/fundamentals/authentication#basic-authentication-3) | * PowerTrack API
* Decahose stream | Requests must use of HTTP Basic Authentication, constructed from a valid email address and password combination. | - -**Connecting** - - -To connect to the Streaming API, form a HTTP request and consume the resulting stream for as long as is practical. Our servers will hold the connection open indefinitely, barring server-side error, excessive client-side lag, network hiccups, routine server maintenance or duplicate logins. - -The method to form an HTTP request and parse the response will be different for every language or framework, so consult the documentation for the HTTP library you are using. - -Some HTTP client libraries only return the response body after the connection has been closed by the server. These clients will not work for accessing the Streaming API. You must use an HTTP client that will return response data incrementally. Most robust HTTP client libraries will provide this functionality. The [Apache HttpClient](http://hc.apache.org/httpcomponents-client-ga/) will handle this use case, for example. - -**Disconnections** - - -X will close a streaming connection for the following reasons: - -* A client establishes too many connections with the same credentials. When this occurs, the oldest connection will be terminated. This means you have to be careful not to run two reconnecting clients in parallel with the same credentials, or else they will take turns disconnecting each other. -* A client stops reading data suddenly. If the rate of Posts being read off of the stream drops suddenly, the connection will be closed. -* A client reads data too slowly. Every streaming connection is backed by a queue of messages to be sent to the client. If this queue grows too large over time, the connection will be closed. -* A streaming server is restarted. This is usually related to a code deploy and is not very frequent. -* X's network configuration changes. These events are rare, and would represent load balancer restarts or network reconfigurations, for example. - -**Stalls** - -Set a timer, either a 90 second TCP level socket timeout, or a 90 second application level timer on the receipt of new data. If 90 seconds pass with no data received, including newlines, disconnect and reconnect immediately according to the backoff strategies in the next section. The Streaming API will send a keep-alive newline every 30 seconds to prevent your application from timing out the connection. You should wait at least 3 cycles to prevent spurious reconnects in the event of network congestion, local CPU starvation, local GC pauses, etc. - -**Reconnecting** - -Once an **established** connection drops, attempt to reconnect immediately. If the reconnect fails, slow down your reconnect attempts according to the type of error experienced: - -* Back off linearly for **TCP/IP level network errors**. These problems are generally temporary and tend to clear quickly. Increase the delay in reconnects by 250ms each attempt, up to 16 seconds. -* Back off exponentially for **HTTP errors** for which reconnecting would be appropriate. Start with a 5 second wait, doubling each attempt, up to 320 seconds. -* Back off exponentially for **HTTP 420 errors**. Start with a 1 minute wait and double each attempt. Note that every HTTP 420 received increases the time you must wait until rate limiting will no longer will be in effect for your account. - -**Connection churn** - -Repeatedly opening and closing a connection (churn) wastes server resources. Keep your connections as stable and long-lived as possible. - -Avoid mobile (cellular network) connections from mobile devices. WiFi is generally OK. - -Delay opening a streaming connection in cases where the user may quit the application quickly. - -If your client works in an environment where the connection quality changes over time, attempt to detect flaky connections. When detected, fall back to REST polling until the connection quality improves. - -**Rate limiting** - -Clients which do not implement backoff and attempt to reconnect as often as possible will have their connections rate limited for a small number of minutes. Rate limited clients will receive HTTP 420 responses for all connection requests. - -Clients which break a connection and then reconnect frequently (to change query parameters, for example) run the risk of being rate limited. - -X does not make public the number of connection attempts which will cause a rate limiting to occur, but there is some tolerance for testing and development. A few dozen connection attempts from time to time will not trigger a limit. However, it is essential to stop further connection attempts for a few minutes if a HTTP 420 response is received. If your client is rate limited frequently, it is possible that your IP will be blocked from accessing X for an indeterminate period of time. - -**Best practices** - -#### Test backoff strategies - -A good way to test a backoff implementation is to use invalid authorization credentials and examine the reconnect attempts. A good implementation will not get any 420 responses. - -#### Issue alerts for multiple reconnects - -If a client reaches its upper threshold of its time between reconnects, it should send you notifications so you can triage the issues affecting your connection. - -#### Handle DNS changes - -Test that your client process honors the DNS Time To live (TTL). Some stacks will cache a resolved address for the duration of the process and will not pick up DNS changes within the proscribed TTL. Such aggressive caching will lead to service disruptions on your client as X shifts load between IP addresses. - -#### User Agent - -Ensure your user-agent HTTP header includes the client’s version. This will be critical in diagnosing issues on X's end. If your environment precludes setting the user-agent field, then set an x-user-agent header. - -**HTTP Error Codes** - -Most error codes are returned with a string with additional details. For all codes greater than 200, clients should wait before attempting another connection. See the Connecting section, above. - -| | | | -| :--- | :--- | :--- | -| Status | Text | Description | -| **200** | **Success** | Self evident. | -| **401** | **Unauthorized** | HTTP authentication failed due to either:

* Invalid basic auth credentials, or an invalid OAuth request.
* Out-of-sync timestamp in your OAuth request (the response body will indicate this).
* Too many incorrect passwords entered or other login rate limiting. | -| **403** | **Forbidden** | The connecting account is not permitted to access this endpoint. | -| **404** | **Unknown** | There is nothing at this URL, which means the resource does not exist. | -| **406** | **Not Acceptable** | At least one request parameter is invalid. For example, the filter endpoint returns this status if:

* The track keyword is too long or too short.
* An invalid bounding box is specified.
* Neither the track nor follow parameter are specified.
* The follow user ID is not valid. | -| **413** | **Too Long** | A parameter list is too long. For example, the filter endpoint returns this status if:

* More track values are sent than the user is allowed to use.
* More bounding boxes are sent than the user is allowed to use.
* More follow user IDs are sent than the user is allowed to follow. | -| **416** | **Range Unacceptable** | For example, an endpoint returns this status if:

* A count parameter is specified but the user does not have access to use the count parameter.
* A count parameter is specified which is outside of the maximum/minimum allowable values. | -| **420** | **Rate Limited** | The client has connected too frequently. For example, an endpoint returns this status if:

* A client makes too many login attempts in a short period of time.
* Too many copies of an application attempt to authenticate with the same credentials. | -| **503** | **Service Unavailable** | A streaming server is temporarily overloaded. Attempt to make another connection, keeping in mind the connection attempt rate limiting and possible DNS caching in your client. | - -### Rule limits - -X will now begin to enforce long-held contractual limits for the number of rules that a customer is able to add to their stream by enforcing rule limits on PowerTrack. While these limits have always been observed, we are now making it easier for customers to know where their limits stand and how close they are to their cap. Functionality has been added to our console that will allow you to observe your current rule count for each product and stream. This information can be found on the right hand side of a product page just under the activity counter (see below). - - - - -This can also be found under the rules section of the usage tab (see below). - - - - -**What If I Hit My Cap?** -If you attempt to upload more rules to your stream that you are contractually allowed, you will receive the following message: - -_“Request exceeds account’s Rule Limit. Delete rules or contact your account manager to proceed.”_ - -If you encounter this error message while you have an open connection, your stream will not be disrupted. In order to add more rules once you hit your cap, you will either need to delete rules from your stream or reach out to your account manager to increase your contractual limit. - - -### Recovery and redundancy features - -#### Introduction - -With streaming high volumes of realtime Posts comes a set of best practices that promote both data reliability and data full-fidelity. When consuming realtime data, maximizing your connection time is a fundamental goal. When disconnects occur, it is important to automatically detect that and reconnect. After reconnecting it’s important to assess if there are any periods to backfill data for. The component that manages these details and consumes realtime Posts is only one part of a system with network, datastore, server, and storage concerns. Given the complexity of these systems, another best practice is to have different streaming environments, with at least separate streams for development/testing and production. - -PowerTrack comes with a set of features that help with these efforts. - -To support multiple environments, we can deploy [Additional Streams](/x-api/enterprise-gnip-2.0/powertrack-api#recovery-and-redundancy-features) for your account. These streams are completely independent of each other, having unique URLs and separate rule sets. - -To help support maintaining a connection, each realtime PowerTrack stream supports [Redundant Connections](/x-api/enterprise-gnip-2.0/powertrack-api#redundant-connections). The most common architecture is for a stream to have two connections, and on the client-side there are two independent consumers, ideally on different networks. With this design, there can be redundancy across the client-side networks, servers, and datastore pathways. Note that a full-copy of the data is served on each connection (since there is a single ‘source’ server and no partitioning with filtered streams) and the client-side must be tolerant of and manage these duplicate data. - -For detecting disconnects, each stream has a ‘heartbeat’ signal that can used to detect when a stream has timed-out. These 10-second heartbeats provide connection confirmation even when there are time periods with no Posts matching your rules and being delivered on your stream. For most X stream consumers, the data volumes are high enough that even a smaller duration of no Posts is a sign of a connection issue. So both a ‘data silence’ and lack of a heartbeat can be used to detect a disconnect. - -Since disconnects will happen, PowerTrack has a dedicated [Recovery](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) and a PowerTrack [Backfill](/x-api/enterprise-gnip-2.0/powertrack-api#backfill) feature to help recover data that was missed due to disconnections and other operational issues. To learn more about disconnects see our support article [HERE](/x-api/enterprise-gnip-2.0/powertrack-api#disconnections-explained). -  - -#### Additional streams  - -Having additional PowerTrack streams is another way to help build reliability into your solution. So much so that it is considered a best practice. Any additional streams are completely independent, having their unique endpoint and independent rule set. Each stream is assigned its own ‘label’, and this label, along with your account name, are part of that stream’s URL. - -https://gnip-stream.x.com/stream/powertrack/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json - -The most common convention is to have a realtime stream dedicated for your production system, and an additional stream available for development and testing. Having a test/development stream enables PowerTrack customers to have a stream to test client consumer updates. While any (unique) label can be assigned to a stream, one convention is to use ‘prod’ for production stream, and ‘dev’ or ‘sandbox’ for an additional development stream. - -The number of streams, and their unique labels, is configurable by your account representative. -  - -#### Redundant connections  - -A redundant connection simply allows you to establish more than 1 simultaneous connections to the data stream. This provides redundancy by allowing you to connect to the same stream with two separate consumers, receiving the same data through both connections. Thus, your app has a hot failover for various situations, e.g. where one stream is disconnected or where your app’s primary server fails. - -The number of connections allowed for any given stream is configurable by your account representative. To use a redundant stream, simply connect to the same URL used for your primary connection. The data for your stream will be sent through both connections, with both stream connections represented on the stream dashboard. - -Note that for billing purposes, we deduplicate the activity counts you receive through multiple connections such that you are only billed for each unique activity once. -  - -#### Recovery  - - -#### Overview  - -Recovery is a data tool that provides streaming access to a rolling window of recent X historical data. It should be utilized to recover data in scenarios where your consuming application misses data in the real time stream, whether due to disconnecting for a short period, or for any other scenario where you fail to ingest realtime data for a period of time. - -There are different varieties of Recovery streams, corresponding to different types of realtime streams that they complement. PowerTrack Recovery streams are provided to allow customers using realtime PowerTrack to recover data they miss, using the same rules as they use in realtime. - -#### Using Recovery  - -With the Recovery stream, your app can make requests to it that operate in the same manner as requests to existing realtime streams. However, your app must specify parameters in the URL that indicate the time window you are requesting. In other words, a Recovery request asks for “Posts from time A to time B.” These Posts are then delivered through your streaming connection in a manner that mimics the realtime stream. - -Posts are delivered beginning with the first minute of the specified time period, continuing until the final minute is delivered. At that point, a “Recovery Request Completed” message is sent through the connection, and the connection is then closed by Gnip. If your request begins at a time of day where little or no matching results occurred, there will likely be some period of time before the first results are delivered – data will be delivered when Recovery encounters matches in the portion of the archive being processed at that time. When no results are available to deliver, the stream will continue sending carriage-return “heartbeats” through the connection to prevent you from timing out. - -Recovery is intended as a tool for easily recovering data missed due to short disconnects, not for very long time periods like entire days. If the need to recover data for long periods arises, we recommend breaking longer requests into shorter time windows (e.g. two hours) to reduce the possibility of being disconnected mid-request due to internet volatility or other reasons, and to provide more visibility into the progress of long requests. - -#### Data availability - -You can use the Recovery feature to recover missed data within the last 24 hours if you are unable to reconnect with the 5 minute backfill window. - -The streaming recovery feature allows you to have an extended backfill window of 24 hours. Recovery enables you to ‘recover’ the time period of missed data. A recovery stream is started when you make a connection request using 'startTime' and 'endTime' request parameters. Once connected, Recovery will re-stream the time period indicated, then disconnect.   - -You will be able to make 2 concurrent requests to recovery at the same time, i.e. “two recovery jobs”. Recovery works technically in the same way as backfill, except a start and end time is defined. A recovery period is for a single time range. - -| Name | Type | Description | -| :--- | :--- | :--- | -| startTime | date (ISO 8601) | YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339).

Date in UTC signifying the start time to recover from. | -| endTime | date (ISO 8601) | YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339).

Date in UTC signifying the end time to recover to. | - -#### Backfill - -The Backfill feature is used to request up to 5 minutes of stream data that is missed after a disconnect, and is available on PowerTrack and Volume streams as an _optional_ feature. - -To request backfill, you need to add a ‘backfillMinutes=number’ parameter to your connection request, where ‘number’ is the number of minutes (1-5, whole numbers only) to backfill when the connection is made. For example, if you disconnect for 90 seconds, you should add ‘backfillMinutes=2’ to your connection request. Since this request will provide backfill for 2 minutes, including for the 30-second period before you disconnected, your _consumer app must be tolerant of duplicate data_. - -An example PowerTrack connection request URL, requesting a 5 minute backfill, looks like: - -https://gnip-stream.x.com/stream/powertrack/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json?backfillMinutes=5 - -**NOTES:** - -* You do have the option to always use ‘backfillMinutes=5’ when you connect, then handling any duplicate data that is provided. - -* If you are disconnected for more than five minutes, you can recover data using the Recovery. -   - - -**Recovering from disconnect** - -Restarting and recovering from a disconnect involves several steps: - -* Determining length of disconnect time period. - * 5 minutes or less? - * If you have Backfill enabled for stream, prepare connection request with appropriate ‘backfillMinutes’ parameter. - * More than 5 minutes? - * Make a connection request using 'startTime' and 'endTime' request parameters in order to start a recovery stream. The streaming recovery feature allows you to have an extended backfill window of 24 hours. Recovery enables you to 'replay' the time period of missed data. -* Request a new connection. - -### Planning for high-volume social data events - -Major national and global events are often accompanied by dramatic spikes in user activity across social media platforms. Sometimes these events are known about in advance, like the Super Bowl, political elections, and New Year’s celebrations around the world. Other times, the spikes in volume are due to unexpected happenings such as natural disasters, unplanned political events, or surprise pop culture moments like Ellen’s famous selfie Post at the Oscars. - -These bursts of user activity can be short-lived (measured in seconds) or they may be sustained over several minutes’ time. No matter their origin, it is important to consider the impact that they can have on applications consuming realtime data from X. - -Here are some best practices that will help your team prepare for high-volume social data events. - -#### Review your current PowerTrack rules - -* Certain keywords can skyrocket during high volume events, for instance brand mentions when a brand sponsors a major sporting event. -* Be careful to avoid any unnecessary or overly generic PowerTrack rules that may generate unnecessary activity volumes. -* Consider communicating with your clients prior to known high-volume events to help them plan appropriately. - -#### Stress test your application - -Anticipate that burst volumes may reach 5-10x average daily consumption levels. Depending on your PowerTrack rule set, the increase may be much higher. - -#### Optimize to stay connected - -With realtime streams, staying connected is essential to avoid missing data. Your client application should be able to detect a disconnect and have logic to immediately retry its connection, using an exponential backoff if the reconnect attempt fails. - -#### Add built-in buffering on your end - -Building a multi-threaded application is a key strategy for handling high-volume streams. At a high-level, a best practice for managing data streams is to have a separate thread/process that establishes the streaming connection and then writes received JSON activities to a memory structure or a buffered stream reader. This ‘light-weight’ stream processing thread is responsible for handling incoming data, which can be buffered in memory, growing and shrinking as needed. Then a different thread consumes that hash and does the ‘heavy lifting’ of parsing the JSON, preparing database writes, or whatever else your application needs to do. - -#### Optional streaming data recovery tools - -* [PowerTrack Replay](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) is available to recover missed activities should you experience an extended disconnection. -* [PowerTrack Backfill](/x-api/enterprise-gnip-2.0/powertrack-api#recovery-and-redundancy-features) automates data recovery if you disconnect briefly. If you disconnect and reconnect within 5 minutes, your data will be buffered by Gnip and delivered automatically. -* If you are unsure whether your Gnip package includes these recovery features, be sure to contact your Account Manager to learn more. - -#### Global events = global time zones - -* The events may occur after business hours or over the weekend, so be sure that your team is prepared for spikes to occur outside your normal business hours. - -#### Don’t Panic! - -* As always, we recommend that you maintain your connections to X real-time APIs and monitor for any changes in delivery latency. -* X's highly-scalable infrastructure ensures that none of your data will be lost or missed from any temporary increases in this latency. - -### Disconnections explained - -Disconnects from your PowerTrack stream can happen for a handful of reasons - whether they proactively planned or unplanned. Regardless of whether or not they were planned, any sort of disconnect can be surprising cause for data loss, but they don’t have to be. A basic understanding of the types of disconnects that you might encounter and how to quickly reconnect can mean the difference between a major issue and something that can be incorporated into your application design by reconnecting, or using Backfill or [Recovery](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api). Please note that for any disconnect, forced or client-side, your [console.gnip.com dashboard](https://console.gnip.com/) will have a message that displays the kind of disconnect that you experienced and a timestamp for the disconnect. - -This article will go over the types of disconnects you might encounter, how to minimize their effects, and how to troubleshoot issues related to disconnects. -  - -#### Forced disconnects - -At the highest level, forced disconnects happen when X actively closes your connection to the stream. These can happen for a variety of reasons, and when you are force disconnected from your stream then X will send a zero byte chunk in accordance with [HTTP chunked encoding practice](http://www.httpwatch.com/httpgallery/chunked/). In all cases of forced disconnects, you should be able to reconnect to the stream immediately and you should be sure to have reconnect logic written into your code to prevent further data loss. - -There are three types of forced disconnects that your app will need to be prepared for. -  - -**X maintenance** - -X deploys for ongoing maintenance several times a week. During these updates, sometimes customer streams will experience one or more disconnects. This will be accompanied by a “X is closing for operational reasons” message. These should be expected disconnections, and your application should be able to reconnect immediately, so make sure that you have reconnect logic written into your application. -  - -**Full buffer disconnect** - -A full buffer disconnect generally indicates that your application’s code isn’t keeping up with the amount of data that we’re streaming to you and there is a backup of cached data on the X server side for your connection which needs to be flushed. This can happen after a major rule change, a [big event](/x-api/enterprise-gnip-2.0/powertrack-api#planning-for-high-volume-social-data-events), or simply because your application is having trouble consuming the stream. Full buffer disconnects are triggered when your stream connection buffer hits a certain threshold of Posts. If you are disconnected for a full buffer, reconnecting with [backfill](/x-api/enterprise-gnip-2.0/powertrack-api#backfill) is not available and data will begin streaming from the time you reconnect. It's likely that you will need to run a [Recovery](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) to recover Posts lost in the disconnection. If you find that full buffer disconnects are happening frequently, reach out to the support team to assist you in making sure that your application is properly configured.  - -Here are some suggestions to prevent these kinds of disconnects from occurring in the future: - -1. Ensure nothing is slowing down the process reading from the stream. Do not do any processing in the process/thread that is reading from the stream. Instead, have this process read the message then pass off any processing (such as parsing, date calculations, etc) of the message to a separate process or thread. -2. Verify there are no network issues between your application and X preventing messages from being sent. -3. Make sure you have sufficient bandwidth for the volume of activities on your stream.  Some streams can have high volumes requiring significant bandwidth (~10 Mbps is not unheard of). Keep in mind these streams require this bandwidth to be sustained 24 hours a day, including spikes that may cause 2-3 times the volume during significant world events. These spikes are often absorbed by X's buffer, and are one of the reasons it is in place. -   - -**Too many connections** - -Each stream is configured to allow for a specified number of connections. This number is determined between you and your account manager, and is available in your account agreement. If you connect to your stream with more connections than are allowed, you will be force disconnected. Any extra connections are allowed for approximately one minute. If after one minute an extra connection exists, the most recent connection is forced disconnected. Allowing an extra connection for a minute enables the customer to, for example, spin up a new server and connect with it, then teardown a server that is being ‘retired.’ -  - -#### Client disconnects - -A client disconnect is essentially any disconnection that occurs which isn’t initiated by our servers. There are many causes for this. Sometimes this could be caused by the code or the architecture of your application, but this often occurs when something in the internet or network layer cuts off the connection. This section provides a list of the most common causes for a client disconnects. -  - -**Issues at the network layer** - -Routing issues at the networking level can cause disconnects. For example, a Border Gateway Protocol (BGP) update can go awry, and clients can disconnect as routers fail to keep up with the sudden additional load put on them when a route fails. As network operators cooperate to reroute traffic, you may notice a pattern of disconnects for some time. -  - -**Firewall configuration** - -Clients may have firewalls set up with session limits that cut off the connections after a certain amount of time, which they need to create exceptions for. From our side, our servers just see the connection close, so we don’t have a way to see whether it was closed by the proactive actions of your app, or just something related to the internet connection between your client and the X servers. -  - -**Data burst and packet loss** - -Clients should be designed to handle spikes in the volume of Posts received. If a client is slow to consume a stream, it will receive a [full buffer disconnect](#full_buffer_disconnect). However, there are situations where the client is not able to handle a sudden surge in volume (for example, after significant rule activity) which will cause the client to drop packets. When this happens, you may notice the client resetting a TCP/IP connection. In certain cases, the connection is terminated correctly and cleanly; however, there may be situations where the underlying networking layer doesn't close the socket properly, or does so after a set delay. In your dashboard, this event will be reported as a client disconnect. In such cases, clients must be sized to handle multiple times the average Post volume. It can be beneficial to examine the network traffic to detect any pattern that leads the client to drop packets. -  - -**Failure to reconnect after a disconnection** - -Occasionally, some customers have trouble reconnecting to their stream after they’ve terminated a connection. Assuming there are no operational issues posted on our [Status Page](https://api.twitterstat.us/), one reason might be that something within your code is keeping the connection alive. In these scenarios, we see something in the layer outside of your app persisting, because the connection wasn’t properly terminated. Generally we see similar behavior when the HTTP client portion of the code isn’t getting proactively closed. It might also be that there is simply some network latency or delay set at the configuration level preventing the request from going through. - - -## Frequently asked questions - -### Realtime PowerTrack API - -**I am interested in X data and would like to find out approximate subscription costs.** - -Please fill out [this form](/x-api/enterprise-gnip-2.0/enterprise-gnip) to get in touch with our Sales team. -  - -**What are some of the features provided by realtime PowerTrack?** - -By connecting directly to our data services, you can take advantage of many enterprise-ready features that provide reliable connectivity and full-fidelity data. As an enterprise licensed-access offering, realtime PowerTrack includes tools for dynamic filtering, consistent connection, data recovery and data compliance management. This technology, paired with operational monitoring, guaranteed support and integration services allows businesses to start with a strong foundation to serve their own customers. - -These features include: - -* Dynamic rule updates while connected to the stream. There is no need to disconnect your stream while you update your stream’s ruleset. -* Support for multiple connections to each stream. -* Ability to automatically recover data that is missed during brief disconnects when you reconnect within 5 minutes with Backfill. -* Availability of Recovery feature to recover missed data within the last 24 hours if you are unable to reconnect with the 5 minute backfill window. -* Availability of additional streams for testing and development. -* Status dashboard to communicate with customers about any operational issues. -   - -**How do I consume streaming data?** - -Realtime streams of data are initiated by sending a HTTP GET command to your custom `https://gnip-stream.x.com` URL. HTTP streaming connections are requested with HTTP headers that indicate a ‘keep-alive’ connection. More information on realtime streaming is available [here](/x-api/enterprise-gnip-2.0/powertrack-api). - -Given the potential of high volumes of X data delivered in a stream, it is highly recommended that incoming data is processed in an asynchronous fashion. What this means is that your code that ‘hosts’ the client side of the stream simply inserts incoming Posts into a (FIFO) queue, or similar memory structure, and then you have a separate process/thread that consumes Posts from that queue and does more of the ‘heavy lifting’ of parsing and preparing the data for storage. With this design, you can implement a process that will bend but not break in case incoming data volumes change dramatically. -  - -**How can multiple customers, projects, and campaigns be managed in a single stream?** - -The vast majority of realtime PowerTrack users manage multiple customers, projects, and campaigns within a single realtime stream by using [PowerTrack rule ‘tags’](/x-api/enterprise-gnip-2.0/powertrack-api). Rule tags have no special meaning, they are simply treated as opaque strings carried along with the rule. They will be included in the “matching rules” metadata in activities returned. - -Tags provide an easy way to create logical groupings of PowerTrack rules. For example, you may generate a unique ID for a specific rule as its tag and allow your application to reference that ID within activities it processes to associate a result with specific customers, campaigns, categories, or other related groups. -  - -**How many connections to a given PowerTrack stream can I have at one time?** - -PowerTrack streams support multiple connections to a single endpoint. Having multiple connections enables customers to build redundant data consumer clients, ideally on different networks. While PowerTrack streams default to a single connection, many customers prefer to have two connections per PowerTrack stream to ensure continuous delivery. If multiple connections are made to a single endpoint, and/or multiple streams exist with common rules, a given Post will be received multiple times. Note that for accounting purposes, the Post will be counted once. - -Please talk to your Account Manager for more information. -  - -**How 'realtime' are the results? Is there any delay/elaboration time between the publication of a Post on X and their release on the PowerTrack stream?** - -Posts that match your ruleset will be delivered to your stream within seconds of being published on the platform. There are variables, such as network connectivity and how your consuming application reads data off the stream; but all things being equal, you should receive Posts within seconds of them being published. - -Please note that the URL enrichment does cause an increased latency, due to the unwinding of each URL in the Post.  - -Generally speaking, you should expect Volume streams (e.g. Firehose and [Decahose](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api)) to be faster than [PowerTrack](/x-api/enterprise-gnip-2.0/powertrack-api), and PowerTrack to be fast than [statuses/filter](https://developer.x.com/en/docs/x-api/v1/tweets/filter-realtime/api-reference/post-statuses-filter). -  - -**Is it possible to update several rules in one go?** - -Yes, you can add or delete several rules with one request. - -However, note that the add and delete steps are separate and you will need two requests: one request to add one or several rule(s) and another request to delete one or several rule(s). - -The upper limit number of rules that can either be added or be deleted in one go is a JSON body that is 5MB or less in size. Depending on the length of your rule values and tags, the upper number will be in the lower thousands. -  - -**Why isn't my rule appearing on the stream right away?** - -Most rule additions take effect almost immediately. However, depending on factors such as network connectivity and rule size/complexity, it may take up to 5 minutes before you start receiving matching Posts. -  - -**What if some Posts are missing: I was expecting them to be returned by the stream, but they weren't?** - -You can follow the next few steps to understand why some Posts might not have been delivered: - -1. Check your [rule](/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering#enterprise-operators) and ensure that you are using the correct operators. -2. Were you connected to the stream when the Post was created? You can use the 'Connections' tab in the [console](https://console.gnip.com) to check your connection history. -3. Was your rule already in place when the Post was created? -4. Note that if the account from which the Post was sent was private at the time the Post was created, the Post won't be returned - even if the account is public at the time of the request. - - -**If I lose the connection to the stream and then connect back, will I lose all Posts from that duration?** - -Yes, if you lose the connection to the stream, you may be missing data for the period of time that you were disconnected from the stream. Whenever a disconnection occurs, your client app must restart the process by establishing a new connection. - -Additionally, to ensure that you do not miss any data, you may need to utilize a [Redundant Connection](/x-api/enterprise-gnip-2.0/powertrack-api#redundant-connections), [Backfill](/x-api/enterprise-gnip-2.0/powertrack-api#backfill), or a [Replay stream](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) to mitigate or recover data from disconnections from the stream. Please see our answer to the next question for more information. -  - -**What if I get disconnected from the stream? How can I collect any data that was missed while disconnected?** - -When streaming data, the goal is to stay connected for as long as possible, recognizing that disconnects will occur. PowerTrack streams provide a 15-second heartbeat (in the form of a new-line character) that enable client applications to detect disconnects. When fresh data and the heartbeat stop arriving, reconnection logic should be triggered. In most software languages this can be easily implemented by setting a data read timeout. - -Any time you disconnect from the stream, you are potentially missing data that would have been sent if connected. However, there are multiple ways to mitigate these disconnects and recover data when they occur. - -There is a range of tools available for retrieving historical posts, including: - -1. [Redundant Streams](/x-api/enterprise-gnip-2.0/powertrack-api#redundant-connections) \- With multiple connections, consume the stream from multiple servers to prevent missed data when one is disconnected. -2. [Recovery](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) \- Recover data within the last 24 hours. -3. [Backfill](/x-api/enterprise-gnip-2.0/powertrack-api#backfill) \- Reconnect within 5 minutes and start from where you left off. -4. [Full Archive Search](/x-api/enterprise-gnip-2.0/fundamentals/search-api#getting-started-with-enterprise-search-posts-full-archive-api) \- Recover data from the entire X archive. - - -Please also refer to [our documentation on disconnects](/x-api/enterprise-gnip-2.0/powertrack-api#disconnections-explained). -  - -**How fast is the streaming speed of Recovery?** - -Recovery will deliver up to 1000 posts per second. It is intended to deliver the posts for the period of time that a customer is disconnected. - -**Do you have any realtime PowerTrack code examples I can use to get started with?** - -Yes, we have several realtime code examples available, including: - -* [Sample Python scripts](https://github.com/xdevplatform/enterprise-scripts-python) -* [Sample Ruby scripts](https://github.com/xdevplatform/ruby-enterprise-scripts/tree/master/PowerTrack) - -Note that these are only available to enterprise customers. - -** -How do Edit Posts impact my usage and billing? ** - -Only the original Post will count for billing purposes. Any subsequent edits will be ignored and not contribute to your overall activity count.  - -### Error troubleshooting guide - -**Code 429 - Rate Limited: Your app has exceeded the limit on requests to add, delete, or list rules for this stream** - -You may be receiving the 429 error code because you are adding or deleting rules too quickly. If you are adding or deleting rules individually, this could add up and exceed the rate limit. - -A workaround could be to add or delete several rules at one time. - -For example, the below sample cURL command shows you how to delete several rules at once: - - ```bash - curl -v -X POST -uexample@customer.com "https://gnip-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json?_method=delete" -d '{"rule_ids":[734938587381145604,734938587381174273]}" -``` - -You can learn more about adding or deleting rules and the relevant rate limits [here](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-rules-api). -  - -**Code 400** - -A 400 error code normally indicates that the server was unable to process the request sent by the client due to poorly formatted JSON. - -There are many reasons why this might be the case and you will need to double check the format of your JSON query. - -For example, you may need to escape the quotes around the exact phrase match(es) in your rule (as in the example below): - -``` -{"rules":\[{"tag":"test1","value":"coffee OR \\"I love coffee\\""}\]} -``` - -** -Frequent Disconnects - I am experiencing frequent disconnections on the stream and one of the following messages is being returned. Why is this happening?** - -`This stream has been disconnected because your client was unable to keep up with us.` - -`This stream has been disconnected for operational reasons.` - -This kind of error occurs when your stream is not keeping up with the speed at which we are delivering data and your app isn't consuming the data from the stream fast enough. - -We allow delivery to get behind for a period of time, and we have a temporary staging buffer amount for each stream on our side; but if you don't catch up, we initiate a disconnect to allow you to reconnect at the current point in time. Please note that this may lead to data loss (for data that is within the buffer at the time of the full buffer disconnect). - -These can occur around large spikes in data. Generally, we recommend using a buffer process for consuming data quickly that is separate from the processing process. - -You can find out more about optimizing your app to prevent disconnects like this in our articles on [connection](/x-api/enterprise-gnip-2.0/powertrack-api#disconnections-explained) and on consuming streaming data [here](/x-api/enterprise-gnip-2.0/powertrack-api#planning-for-high-volume-social-data-events). - -## API reference index - -For the complete reference, select an API from the list: - -| | | -| :--- | :--- | -| **Add or delete rules from your stream** | [PowerTrack Rules API](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-rules-api) | -| **Connect to your PowerTrack stream** | [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-api)` | -| **Recover Posts lost during an outage** | [Replay API](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) | - - -### PowerTrack API -Jump to on this page - -[Methods](#Methods) - -[Authentication](#Authentication) - -[GET /track/:stream](#Stream) - -#### Methods[](#methods- "Permalink to this headline") - - -| Method | Description | -| :--- | :--- | -| [GET /track/:stream](#Stream) | Connect to the data stream | - -#### Authentication[](#authentication- "Permalink to this headline") - -All requests to the PowerTrack API must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. Make sure your client is adding the "Authentication: Basic" HTTP header (with encoded credentials over HTTPS) to all API requests. - -#### GET /track/:stream[](#get-track-stream- "Permalink to this headline") - -Establishes a persistent connection to the PowerTrack data stream, through which the social data will be delivered. - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **Connection Type** | Keep-Alive

This should be specified in the header of the request. | -| **URL** | Found on the stream's API Help page of your console dashboard, and resembles the following structure:


[https://gnip-stream.x.com/stream/powertrack/accounts/](https://gnip-stream.x.com/stream/powertrack/accounts/){gnip_account_name}/publishers/twitter/{stream_label}.json | -| **Compression** | Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following:

Accept-Encoding: gzip | -| **Character Encoding** | UTF-8 | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | 60 requests per minute. | -| **Read Timeout** | Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds. | -| **Support for Tweet edits** | All Tweet objects will include Tweet edit metadata describing the Tweet's edit history. See the ["Edit Tweets" fundamentals page](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) for more details. | - -#### Responses - -The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | Success | The connection was successfully opened, and new activities will be sent through as they arrive. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 406 | Not Acceptable | Generally, this occurs where your client fails to properly include the headers to accept gzip encoding from the stream, but can occur in other circumstances as well.

Will contain a JSON message similar to "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end." | -| 429 | Rate Limited | Your app has exceeded the limit on connection requests. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support or emergency if unable to connect after 10 minutes. | - - - -**Example curl Request** - -The following example request is accomplished using cURL on the command line. However, note that these requests may also be sent with the programming language of your choice. -``` -curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/powertrack/accounts/:account\_name/publishers/twitter/:stream\_label.json" -``` - -### Replay API - - -Jump to on this page - -[Methods](#Methods) - -[Authentication](#Authentication) - -[GET /replay](#Stream) - -#### Methods[](#methods- "Permalink to this headline") - - -| Method | Description | -| :--- | :--- | -| [GET /replay/:stream_type](#Stream) | Connect to the replay stream. For realtime PowerTrack, the Stream Type is 'powertrack'. For Volume Streams, Stream Types include 'sample10' (i.e. decahose), 'firehose', 'mentions', and 'compliance'. | - -#### Authentication[](#authentication- "Permalink to this headline") - -All requests to the Replay API must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. - -#### GET /replay[](#get-replay- "Permalink to this headline") - -Establishes a connection to the Replay data stream. Tweet data will be delivered for the time period specified, and user profile objects will reflect the referenced users at the time when the Replay API is running. - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **Connection Type** | Keep-Alive

This should be specified in the header of the request. | -| **URL** | Found on the stream's API Help page of your dashboard, the URL is built with Stream Type, Account Name and Stream Label tokens. For realtime PowerTrack, the Stream Type is 'powertrack'. For Volume Streams, Stream Types include 'sample10' (i.e. decahose), 'firehose', 'mentions', and 'compliance'.

Replay URLs have the following pattern:


[https://gnip-stream.gnip.com/replay/](https://gnip-stream.gnip.com/replay/){STREAM_TYPE}/accounts/{ACCOUNT_NAME}/publishers/twitter/{STREAM_LABEL}.json


For example, the Replay URL for realtime PowerTrack has the following pattern:


[https://gnip-stream.gnip.com/replay/powertrack/accounts/](https://gnip-stream.gnip.com/replay/powertrack/accounts/){ACCOUNT_NAME}/publishers/twitter/{STREAM_LABEL}.json


For example, the Replay URL for Decahose has the following pattern:


[https://gnip-stream.gnip.com/replay/sample10/accounts/](https://gnip-stream.gnip.com/replay/sample10/accounts/){ACCOUNT_NAME}/publishers/twitter/{STREAM_LABEL}.json | -| **Compression** | Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following:

Accept-Encoding: gzip | -| **Character Encoding** | UTF-8 | -| **Response Format** | JSON. The header of your request should specify JSON format for the response. | -| **Rate Limit** | 5 requests per 5 minutes. | -| **fromDate** | The oldest (starting) UTC timestamp from which the activities will be provided, must be in 'YYYYMMDDHHMM' format. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute). Valid times must be within the last 5 days, UTC time, and no more recent than 31 minutes before the current point in time. It's recommended that the fromDate and toDate should be within ~2 hours. | -| **toDate** | The latest (ending) UTC timestamp to which the activities will be provided, must be in 'YYYYMMDDHHMM' format. Timestamp is in minute granularity and is exclusive (i.e. 12:30 does not include the 30th minute of the hour). Valid times must be within the last 5 days, UTC time, and no more recent than 30 minutes before the current point in time. It's recommended that the fromDate and toDate should be within ~2 hours. | -| **Read Timeout** | Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds. | -| **Support for Tweet edits** | Since all Replay requests are for Tweets posted at least 30 minutes ago, all Tweets returned by Replay will reflect their final edit state. All Tweet objects will include metadata that describes its edit history. See the ["Edit Tweets" fundamentals](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) page for more details. | - - - -#### Responses - -The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | Success | The connection was successfully opened, and new activities will be sent through until the end of the requested time period is reached, and a "Replay Request Completed" message is sent. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 406 | Not Acceptable | Generally, this occurs where your client either fails to properly include the headers to accept gzip encoding from the stream, or specifies an unacceptable fromDate or toDate.

Will contain a JSON message indicating the issue -- e.g. "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end." or "Invalid date for query parameter 'toDate'. Can't ask for tweets from within the past 30 minutes." | -| 429 | Rate Limited | Your app has exceeded the limit on connection requests. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support. | - - - -#### "Request Completed" Message - -Once a request has been completed, a "Replay Request Completed" message will be delivered through the stream prior to disconnecting inside a "info" JSON message. If your stream is disconnected prior to receiving this message, the request was not completed, and you will need to re-run the missing portion of the request. - -A premature disconnection may occur especially where your client is not consuming activities quickly enough. In this scenario, the connection may send the "Completed" message, but the connection may close prior to your client receiving it due to the slow rate of consumption. In this scenario, your client should re-request the end-portion of the data to ensure completeness, based on the timestamps of the last Tweets received. - -The "info" JSON message has the following structure: - -``` -{ - "info": { - "message": "Replay Request Completed", - "sent": "2016-05-27T22:15:50+00:00", - "activity_count": 8874 - } -} -``` -If any errors are associated with a completed Replay request, the "info" message will indicate that errors occurred and also list the minutes that were effected in the "minutes_failed" field. Here is an example: -``` -{ - "info": { - "message": "Replay Request Completed with Errors", - "sent": "2016-05-27T16:00:02+00:00", - "activity_count": 56333, - "minutes_failed": \[ - "2013-02-20T00:05:00+00:00", - "2013-02-20T00:06:00+00:00" - \] - } -} -``` -Users (or their client applications) should monitor for complete success of the Replay stream, and submit new Replay requests for any minutes that failed. - -#### "Request Failed to Complete" Message - -If a Replay request fails to complete, the "info" message will indicate the failure and also list the time range was was not processed. Here is an example: -``` -{ - "info": { - "message": "Replay Request Failed to Complete", - "sent": "2016-06-27T16:37:13+00:00", - "unprocessed_range": { - "fromDate": "2016-06-26T00:00:00+00:00", - "toDate": "2016-06-26T00:01:00+00:00" - }, - "activity_count": 1822 - } -} -``` -If this message is received another Replay request should be made based on the "fromDate" and "toDate" included in the "unprocessed_range" attribute. - -#### Example curl Request - -The following example request is accomplished using cURL on the command line, and requests the first hour of data from June 1, 2016. -``` -curl --compressed -v -uexample@customer.com "https://gnip-stream.gnip.com/replay/powertrack/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}json?fromDate=201606010000&toDate=201606010100" -``` - -#### Sample streams Replay Examples (Stream Types include 'sample10' (i.e. decahose), 'firehose', 'mentions')[](#sample-streams-replay-examples-stream-types-include-sample10-i-e-decahose-firehose-mentions- "Permalink to this headline") - -Decahose, firehose, mentions note- All partitions from volume streams are delievered in a single Replay connection. -``` -curl --compressed -v -uexample@customer.com -"https://gnip-stream.gnip.com/replay/sample10/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json?fromDate=201712312330&toDate=201801010130" -``` - -#### Compliance Replay Examples[](#compliance-replay-examples "Permalink to this headline") - -Compliance note- All partitions from Compliance Firehose are delievered in a single Replay connection. -``` -curl --compressed -v -uexample@customer.com -"https://gnip-stream.gnip.com/replay/compliance/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json?fromDate=201712312330&toDate=201801010130" -``` -### PowerTrack Replay Examples[](#powertrack-replay-examples "Permalink to this headline") - -Connection to Replay to complete data during the 2018 New Year's eve disconnection: - -``` -curl --compressed -v -uexample@customer.com -"https://gnip-stream.gnip.com/replay/powertrack/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json?fromDate=201712312330&toDate=201801010130" -``` - -Important Note: When using PowerTrack Replay, you must first add or manage the rules currently on the replay stream. PowerTrack rules are not automatically added to a Replay stream from a normal PowerTrack stream. Rules can be managed through the Rules API for a Replay stream. Please see the [PowerTrack Rules API](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-rules-api) for specific details on managing rules. - -Rules management on the PowerTrack replay: -``` -curl -v -X POST -uexample@customer.com -"https://gnip-api.x.com/rules/powertrack-replay/accounts/{ACCOUNT\_NAME}/publishers/twitter/{STREAM\_LABEL}.json" --d '{"rules":\[{"value":"rule1","tag":"tag1"},{"value":"rule2"}\]}' -``` - -### PowerTrack Rules API - - -Jump to on this page - -[Methods](#Methods) - -[Authentication](#Authentication) - -[POST /rules](#AddRules) - -[GET /rules](#ListRules) - -[GET /rules/:rule_id](#GetRule) - -[POST /rules _method=get](#GetRules) - -[POST /rules _method=delete](#DeleteRules) - -[POST /validation](#ValidateRules) - -#### Methods[](#methods- "Permalink to this headline") - - -| Method | Description | -| :--- | :--- | -| [POST /rules](#AddRules) | Add rules to the stream | -| [GET /rules](#ListRules) | Retrieve all rules currently in place on the stream | -| [GET /rules/:rule_id](#GetRule) | Retrieve an existing rule on the stream by rule ID | -| [POST /rules _method=get](#GetRules) | Retrieve multiple rules on the stream by rule IDs | -| [POST /rules _method=delete](#DeleteRules) | Delete rules from the stream | -| [POST /validation](#ValidateRules) | Validate PowerTrack rule syntax | - -#### Authentication[](#authentication- "Permalink to this headline") - -All requests to the PowerTrack rules API must use HTTP Basic Authentication, constructed from a valid email address and password combination used to log into your account at console.gnip.com. Credentials must be passed as the Authorization header for each request. Make sure your client is adding the "Authentication: Basic" HTTP header (with encoded credentials over HTTPS) to all API requests. - -#### POST /rules[](#post-rules- "Permalink to this headline") - - -Adds one or many rules to your PowerTrack stream's ruleset. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **Content Type** | "application/json". The request should specify this as the "Content-type". | -| **URL** | Found on the [Console - Products API Help tab](/x-api/enterprise-gnip-2.0/fundamentals/overview#products-tab), and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json` | -| **Character Encoding** | UTF-8 | -| **Request Body Format** | JSON | -| **Request Body Size Limit** | 5 MB | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). Rule addition requests will be processed serially and will be rejected if you have more than one rule request happening at the same time. | - - - -#### Request Body Content - -Your request should provide rule data in the following format with the defined Content-type: "application/json": -``` - { - "rules": - [ - {"value":"rule1","tag":"tag1"}, - {"value":"rule2","tag":"tag2"} - ] - } -``` - - -**Example curl Request** - -The following example requests demonstrate how to add rules using cURL on the command line, using JSON rules. -``` - curl -v -X POST -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json" -d '{"rules":[{"value":"rule1","tag":"tag1"},{"value":"rule2","tag":"tag2"}]}' -``` - -``` - curl -v -X POST -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json" -d @arrayofrulesfile_max5mb.json -``` - -``` - curl -v -X POST -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/companyname/publishers/twitter/prod.json" -d '{"rules":[{"value":"(#snow OR snowday OR "snow day" OR from:noaa) lang:en","tag":"4581245"},{"value":"(skiing OR boarding OR "hitting the slopes" OR from:OnTheSnow) lang:en","tag":"4581267"}]}' -``` - - -#### Responses - -The following responses may be returned by the API for these requests. Non-200 responses should be retried after making any necessary modifications in the rules. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 201 | Created | The rule or rules were successfully added to your PowerTrack ruleset. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 422 | Unprocessable Entity | Generally occurs due to an invalid rule, based on the PowerTrack rule restrictions. Requests fail or succeed as a batch. For these errors, each invalid rule and the reason for rejection is included in a JSON message in the response. Catch the associated exception to expose this message. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/) contact support or contact emergency if still unable to connect after 10 minutes. | - - - -**Example Responses** - -This response indicates that all rules (two in this case) were successfully created. -``` - HTTP/1.1 201 Created - { - "summary": { - "created": 2, - "not_created": 0 - }, - "detail": [{ - "rule": { - "value": "(#snow OR snowday OR \"snow day\" OR from:noaa) lang:en", - "tag": "4581245", - "id": 734938587381145604 - }, - "created": true - }, { - "rule": { - "value": "(skiing OR boarding OR \"hitting the slopes\" OR from:OnTheSnow) lang:en", - "tag": "4581267", - "id": 734938587381174273 - }, - "created": true - }], - "sent": "2016-05-24T02:46:28.402Z" - } -``` -This response indicates that one rule was successfully created, and two were not created because they already exist. Rules are indexed by rule value (syntax). For rules not created there is a 'message' field explaining why the rule could not be created. -``` - HTTP/1.1 201 Created - { - "summary": { - "created": 1, - "not_created": 2 - }, - "detail": [{ - "rule": { - "value": "robot OR 🤖", - "tag": "botrule123", - "id": 734861971116285952 - }, - "created": true - }, { - "rule": { - "value": "fish OR 🐟", - "tag": "fishrule123" - }, - "created": false, - "message": "A rule with this value already exists" - }, { - "rule": { - "value": "Pizza OR 🍕", - "tag": "pizzarule123" - }, - "created": false, - "message": "A rule with this value already exists" - }], - "sent": "2016-05-23T21:42:01.661Z" - } -``` -The following responses indicate that no rules were created. In each case there is a 'message' field explaining why the rule could not be created. Note that when one or more rules are invalid, no rules are added (even rules with valid syntax). - - -``` - HTTP/1.1 422 Unprocessable Entity - { - "summary": { - "created": 0, - "not_created": 2 - }, - "detail": [{ - "rule": { - "value": "streaming gnip contains:$twtr", - "tag": null - }, - "created": false, - "message": "no viable alternative at input '$twtr' (at position 25)\n" - }, { - "rule": { - "value": "streaming gnip contains:\"$twtr\"", - "tag": null - }, - "created": false - }], - "sent": "2016-06-01T15:41:27.451Z" - } -``` - -``` - HTTP/1.1 422 Unprocessable Entity - { - "summary": { - "created": 0, - "not_created": 1 - }, - "detail": [{ - "rule": { - "value": "-follow", - "tag": null - }, - "created": false, - "message": "Rules must contain a non-negation term (at position 1)\nRules must contain at least one positive, non-stopword clause (at position 1)\n" - }], - "sent": "2016-05-23T18:34:25.218Z" - } -``` - -``` - HTTP/1.1 422 Unprocessable Entity - { - "summary": { - "created": 0, - "not_created": 1 - }, - "detail": [{ - "rule": { - "value": "streaming AND lang:en", - "tag": null - }, - "created": false, - "message": "Ambiguous use of and as a keyword. Use a space to logically join two clauses, or \"and\" to find occurrences of and in text (at position 11)\n" - }], - "sent": "2016-05-23T21:39:49.612Z" - } -``` - - -#### GET /rules[](#get-rules- "Permalink to this headline") - -Retrieve all rules currently in place on the stream - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **URL** | Found on the [Console - Products API Help tab](/x-api/enterprise-gnip-2.0/fundamentals/overview#products-tab), and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json` | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | - - - -**Example cURL Request** - -The following example request demonstrates how to retrieve rules using cURL on the command line. - - curl -v -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json" - -#### Response - -The following responses may be returned by the API for these requests. Non-200 responses should be retried, utilizing an exponential backoff for subsequent requests. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful, and the current ruleset is returned in JSON format. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/) contact support. | - - - -**Example Response** -``` - HTTP/1.1 200 OK - { - "rules": [{ - "value": "from:xdevelopers", - "tag": "tweetsfromxdevelopers", - "id": 735163830813134848 - }, { - "value": "fish OR 🐟", - "tag": "fishrule123", - "id": 738034522583769088 - }, { - "value": "Pizza OR 🍕", - "tag": "pizzarule123", - "id": 738034522579554304 - }, { - "value": "robot OR 🤖", - "tag": "botrule123", - "id": 738034522579570689 - }], - "sent": "2016-06-01T15:52:37.341Z" - } -``` - - -#### GET /rules/:rule_id[](#get-rules-rule-id- "Permalink to this headline") - -Retrieve an existing rule on the stream by rule ID. Note that all rules are assigned a unique ID by X at the time of creation, rules that are deleted and recreated will receive a different unique rule ID. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP GET | -| **URL** | Found on the [Console - Products API Help tab](/x-api/enterprise-gnip-2.0/fundamentals/overview#products-tab), and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label/rules/:rule_id.json` | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | - - - -**Example cURL Request** - -The following example request demonstrates how to retrieve a rule by rule_id using cURL on the command line. - - curl -v -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label/rules/:rule_id.json" - - - - curl -v -uexample@customer.com "https://data-api.x.com/rules/powertrack/accounts/companyname/publishers/twitter/prod/rules/735163830813134848.json" - -#### Response - -The following responses may be returned by the API for these requests. Non-200 responses should be retried, utilizing an exponential backoff for subsequent requests. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful, and the current rule is returned in JSON format. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/) contact support. | - - - -**Example Response** -``` - HTTP/1.1 200 OK - { - "rules": [{ - "value": "from:xdevelopers", - "tag": "tweetsfromxdevelopers", - "id": 735163830813134848 - "id_str":"735163830813134848" - }], - "sent": "2016-06-01T15:52:37.341Z" - } -``` - - -#### POST /rules _method=get[](#post-rules--method-get- "Permalink to this headline") - -Retrieves requested existing rules by list of rule IDs currently on a stream. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | Found on the API Help page, and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json?_method=get` | -| **Character Encoding** | UTF-8 | -| **Request Body Format** | JSON | -| **Request Body Size Limit** | 5 MB | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | -| **Compression** | Gzip compression is supported, but not required for these requests. | - - - -**Example curl Request** - -The following example request demonstrates how to add rules using cURL on the command line. -``` - curl -v -X POST -uexample@customer.com \ - "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json?_method=get" \ - -d '{"rule_ids":[734938587381145604,734938587381174273]}" -``` - - -#### Response - -The following responses may be returned by the API for these requests. Non-200 responses should be retried, utilizing an exponential backoff for subsequent requests. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful, and the current ruleset is returned in JSON format. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/) contact support. | - - - -**Example Response** -``` - HTTP/1.1 200 OK - { - "rules": [{ - "value": "from:furiouscamper", - "tag": null, - "id": 734938587381145604 - }, { - "value": "fish 🐟", - "tag": null, - "id": 734938587381174273 - }], - "sent": "2016-06-01T15:52:37.341Z" - } - - - - { - "error": { - "message": "Invalid JSON. The body must be in the format {\"rules\":[{\"value\":\"rule1\", \"tag\":\"tag1\"}, {\"value\":\"rule2\"}]} or {\"rule_ids\": [rule_id1, rule_id2, rule_id3, rule_id4, rule_id5]}", - "sent": "2013-08-16T00:50:00+00:00" - } - } - -``` - -#### POST /rules _method=delete[](#post-rules--method-delete- "Permalink to this headline") - -Deletes requested existing rules by list of rule values or rule IDs currently on a stream. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **Authentication** | Basic Authentication. Your login credentials must be included in the header of the request. | -| **Content Type** | "application/json". The request should specify this as the "Content-type". | -| **URL** | Found on the API Help page, and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json?_method=delete` | -| **Character Encoding** | UTF-8 | -| **Request Body Format** | JSON | -| **Request Body Size Limit** | 5 MB | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | - - - -#### Request Body Content - -Your request should provide rule data in the following formats: -``` - Content-type: "application/json" - { - "rules": - [ - {"value":"rule1"}, - {"value":"rule2"} - ] - } -``` -``` - Content-type: "application/json" - { - "rule_ids": - [ - 734938587381145604, - 734938587381174273 - ] - } -``` -**Example curl Request** - -The following example request demonstrates how to add rules using cURL on the command line. -``` - curl -v -X POST -uexample@customer.com \ - "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json?_method=delete" \ - -d '{"rules":[{"value":"testrule"}]}" -``` -``` - curl -v -X POST -uexample@customer.com \ - "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label.json?_method=delete" \ - -d '{"rule_ids":[734938587381145604,734938587381174273]}" -``` - - -#### Responses - -The following responses may be returned by the API for these requests. Non-200 responses should be retried following any necessary modifications to the rules being deleted. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | Indicates that the rule data supplied with the request consisted of valid JSON. However, note that if no rules are found in the ruleset for the PowerTrack stream based on a case-sensitive search, no rules will be deleted. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support. | - - - -**Example Responses** -``` - HTTP/1.1 200 OK - { - "summary": { - "deleted": 3, - "not_deleted": 0 - }, - "detail": [], - "sent": "2016-06-01T15:46:48.654Z" - } -``` - -``` - HTTP/1.1 200 OK - { - "summary": { - "deleted": 0, - "not_deleted": 3 - }, - "detail": [{ - "rule": { - "value": "Pizza", - "tag": null - }, - "deleted": false, - "message": "Rule does not exist" - }, { - "rule": { - "value": "eggplant", - "tag": null - }, - "deleted": false, - "message": "Rule does not exist" - }, { - "rule": { - "value": "fish", - "tag": null - }, - "deleted": false, - "message": "Rule does not exist" - }], - "sent": "2016-06-01T15:49:15.951Z" - } -``` -``` - HTTP/1.1 400 Bad Request - { - "error": { - "message": "Invalid JSON. The body must be in the format {\"rules\":[{\"value\":\"rule1\", \"tag\":\"tag1\"}, {\"value\":\"rule2\"}]} or {\"rule_ids\": [rule_id1, rule_id2, rule_id3, rule_id4, rule_id5]}", - "sent": "2013-08-16T00:50:00+00:00" - } - } -``` -**Important note on rule management:** Rule sets are indexed by the value or ruleID, not the tag; therefore, all rule additions must reference the rule value or ruleID. In order to to make a tag update to an existing rule, you must first delete it and then add it back with the new tag value. - -Rules must be unique per stream based on rule value, see below for a rule management example scenario: - -**CREATE RULE** - -Action: POST rule \{"value":"#XData","tag":"tagtextA"} \{"summary":\{"created":1,"not\_created":0},"detail":\[\{"rule":\{"value":"#XData","tag":"tagtextA","id":961664522481119232,"id\_str":"961664522481119232"},"created":true}\],"sent":"2018-02-08T18:14:23.691Z"} System: \{"value":"#XData","tag":"tagtextA","id":961664522481119232,"id_str":"961664522481119232"} - -**FAILED ATTEMPT TO UPDATE TAG** - -Action: POST rule \{"value":"#XData","tag":"tagtextB"} **Rule tags cannot be "updated" - This request is ignored because rule value `#XData` already exists. \{"summary":\{"created":0,"not\_created":1},"detail":\[\{"rule":\{"value":"#XData","tag":"tagtextB","id":961664522481119232,"id\_str":"961664522481119232"},"created":false,"message":"A rule with this value already exists"} System: \{"value":"#XData","tag":"tagtextA","id":961664522481119232,"id_str":"961664522481119232"} - -**FAILED ATTEMPT TO DELETE BY TAG** - -Action: POST method=delete rule \{"tag":"tagtextA"} **Rules cannot be deleted by tag. \{"summary":\{"deleted":0,"not\_deleted":1},"detail":\[\{"rule":\{"value":"","tag":null},"deleted":false,"message":"Rule does not exist"}\],"sent":"2018-02-08T18:42:37.004Z"} System: \{"value":"#XData","tag":"tagtextA","id":961664522481119232,"id\_str":"961664522481119232"} - -**DELETE BY ID** - -Action: POST method=delete rule \{"rule\_ids":\[961664522481119232\]} \{"summary":\{"deleted":1,"not\_deleted":0},"detail":\[\],"sent":"2018-02-08T18:53:54.185Z"} - -**DELETE BY VALUE** - -Action: POST method=delete rule \{"value":"#XData"} \{"summary":\{"deleted":1,"not_deleted":0},"detail":\[\],"sent":"2018-02-08T18:53:54.185Z"} - -**RECREATE RULE- NOW WITH NEW ID** - -Action: POST rule \{"value":"#XData","tag":"tagtextB"} \{"summary":\{"created":1,"not\_created":0},"detail":\[\{"rule":\{"value":"#XData","tag":"tagtextB","id":961675641140609025,"id\_str":"961675641140609025"},"created":true}\],"sent":"2018-02-08T18:58:34.586Z"} System: \{"value":"#XData","tag":"tagtextB","id":961675641140609025,"id_str":"961675641140609025"} - -#### POST /validation[](#post-validation- "Permalink to this headline") - -Validates PowerTrack rules. - -**Note:** Using this endpoint will not impact your PowerTrack streams. - -#### Request Specifications - -| | | -| :--- | :--- | -| **Request Method** | HTTP POST | -| **URL** | Found on the API Help page in console, and uses the following structure: `https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label/validation.json` | -| **Character Encoding** | UTF-8 | -| **Request Body Format** | JSON | -| **Request Body Size Limit** | 5 MB | -| **Rate Limit** | 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | - - - -**Example curl Request** - -The following example request demonstrates how to add rules using cURL on the command line. -``` - curl --compressed -v -uexample@customer.com \ - "https://data-api.x.com/rules/powertrack/accounts/:account_name/publishers/twitter/:stream_label/validation.json" \ - -d '{ - "rules": [{ - "value": "Pizza OR 🍕 OR \"🍕\" sample:100" - }, { - "value": "from:contains:heart" - }, { - "value": "fish AND bird" - }, { - "value": "(((\"#quotedhashtag\"" - }, { - "value": "bounding_box:[-71.199636,42.230046,-70.979909,42.398619]" - }, { - "value": "from:jack" - }] - }' -``` -#### Response - -The following responses may be returned by the API for these requests. Non-200 responses should be retried, utilizing an exponential backoff for subsequent requests. - -| Status | Text | Description | -| :--- | :--- | :--- | -| 200 | OK | The request was successful, and the rule validation result is returned. | -| 400 | Bad Request | Generally relates to poorly formatted JSON, and includes an "Invalid JSON" message in the response. | -| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. | -| 429 | Rate Limited | Your app has exceeded the limit on requests to add, delete, or list rules for this stream. | -| 503 | Service Unavailable | X server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on the [X API Status Page](https://api.twitterstat.us/), contact support. | - - - -**Example Response** - -This response indicates that one rule is valid and five are not valid. For rules that are not valid, there is a 'message' field explaining why the rule is not valid. -``` - HTTP/1.1 200 OK - { - "summary": { - "valid": 1, - "not_valid": 5 - }, - "detail": [{ - "rule": { - "value": "from:jack", - "tag": null - }, - "valid": true - }, { - "rule": { - "value": "Pizza OR 🍕 OR \"🍕\" sample:100", - "tag": null - }, - "valid": false, - "message": "The sample operator cannot be used with an OR. To use the sample operator with an OR in the rule, the ORed clauses must be grouped together with parenthesis. For example, to get 10% of activites that have term1 or term2, the rule should be (excluding the single quotes) '(term1 OR term2) sample:10' (at position 21)\n" - }, { - "rule": { - "value": "from:contains:heart", - "tag": null - }, - "valid": false, - "message": "Cannot parse rule at ':' (position 14)\n" - }, { - "rule": { - "value": "fish AND bird", - "tag": null - }, - "valid": false, - "message": "Ambiguous use of and as a keyword. Use a space to logically join two clauses, or \"and\" to find occurrences of and in text (at position 6)\n" - }, { - "rule": { - "value": "(((\"#quotedhashtag\"", - "tag": null - }, - "valid": false, - "message": "mismatched input 'EOF' expecting ')' (at position 20)\n\n" - }, { - "rule": { - "value": "bounding_box:[-71.199636,42.230046,-70.979909,42.398619]", - "tag": null - }, - "valid": false, - "message": "Cannot parse rule at '71.199636,42.230046,-70.979909,42.398619' (position 16)\n" - }], - "sent": "2017-03-16T02:33:01.827Z" - } -``` +[See Complete List of Operators »](/x-api/enterprise-gnip-2.0/powertrack-api#available-o \ No newline at end of file diff --git a/x-api/general/get-openapi-spec.mdx b/x-api/general/get-openapi-spec.mdx index 43965049f..387afc47a 100644 --- a/x-api/general/get-openapi-spec.mdx +++ b/x-api/general/get-openapi-spec.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/openapi.json ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/lists/add-list-member.mdx b/x-api/lists/add-list-member.mdx index f15a29856..1288c9196 100644 --- a/x-api/lists/add-list-member.mdx +++ b/x-api/lists/add-list-member.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/lists/{id}/members ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/lists/create-list.mdx b/x-api/lists/create-list.mdx index 95b1c45f4..7da6ceeb7 100644 --- a/x-api/lists/create-list.mdx +++ b/x-api/lists/create-list.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/lists/delete-list.mdx b/x-api/lists/delete-list.mdx index 791bf070f..81e953c7c 100644 --- a/x-api/lists/delete-list.mdx +++ b/x-api/lists/delete-list.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/lists/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/lists/get-list-by-id.mdx b/x-api/lists/get-list-by-id.mdx index 968001063..5ced14a51 100644 --- a/x-api/lists/get-list-by-id.mdx +++ b/x-api/lists/get-list-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/lists/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/lists/get-list-followers.mdx b/x-api/lists/get-list-followers.mdx index d06609491..d80aaaaf8 100644 --- a/x-api/lists/get-list-followers.mdx +++ b/x-api/lists/get-list-followers.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/lists/{id}/followers ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/lists/get-list-members.mdx b/x-api/lists/get-list-members.mdx index fed3c12a8..4e0bbf37f 100644 --- a/x-api/lists/get-list-members.mdx +++ b/x-api/lists/get-list-members.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/lists/{id}/members ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/lists/get-list-posts.mdx b/x-api/lists/get-list-posts.mdx index bca06c29b..7f2654c1d 100644 --- a/x-api/lists/get-list-posts.mdx +++ b/x-api/lists/get-list-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/lists/{id}/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/lists/list-lookup/integrate.mdx b/x-api/lists/list-lookup/integrate.mdx index 1ed7acceb..ffc937efa 100644 --- a/x-api/lists/list-lookup/integrate.mdx +++ b/x-api/lists/list-lookup/integrate.mdx @@ -1,281 +1,280 @@ ---- -title: Integration Guide -sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating List lookup -keywords: ["list lookup integration", "lists integration guide", "list lookup implementation"] ---- - -import { Button } from '/snippets/button.mdx'; - -This guide covers the key concepts you need to integrate the List lookup endpoints into your application. - ---- - -## Authentication - -List lookup endpoints support multiple authentication methods: - -| Method | Best for | Access to private Lists? | -|:-------|:---------|:-------------------------| -| [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) | Public List data | No | -| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | User-facing apps | Yes (owned/followed) | -| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy integrations | Yes (owned/followed) | - -### Example request - - - -```bash cURL -curl "https://api.x.com/2/lists/84839422?\ -list.fields=description,member_count,follower_count,private" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get a List by ID -response = client.lists.get( - list_id="84839422", - list_fields=["description", "member_count", "follower_count", "private"] -) -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -const response = await client.lists.get("84839422", { - listFields: ["description", "member_count", "follower_count", "private"], -}); -console.log(response.data); -``` - - - ---- - -## Endpoints overview - -| Method | Endpoint | Description | -|:-------|:---------|:------------| -| GET | [`/2/lists/:id`](/x-api/lists/get-list) | Get List by ID | -| GET | [`/2/users/:id/owned_lists`](/x-api/users/get-owned-lists) | Get Lists owned by a user | - ---- - -## Fields and expansions - -### Default response - -```json -{ - "data": { - "id": "84839422", - "name": "Tech News" - } -} -``` - -### Available fields - - -| Field | Description | -|:------|:------------| -| `created_at` | List creation timestamp | -| `description` | List description | -| `follower_count` | Number of followers | -| `member_count` | Number of members | -| `owner_id` | Owner's user ID | -| `private` | Whether List is private | - - - -| Field | Description | -|:------|:------------| -| `username` | Owner's @handle | -| `name` | Owner's display name | -| `verified` | Owner's verification status | -| `profile_image_url` | Owner's avatar URL | - - -### Example with expansions - - - -```bash cURL -curl "https://api.x.com/2/lists/84839422?\ -list.fields=description,member_count,follower_count,owner_id&\ -expansions=owner_id&\ -user.fields=username,verified" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get List with owner expansion -response = client.lists.get( - list_id="84839422", - list_fields=["description", "member_count", "follower_count", "owner_id"], - expansions=["owner_id"], - user_fields=["username", "verified"] -) - -print(response.data) -print(response.includes) # Contains owner user object -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -const response = await client.lists.get("84839422", { - listFields: ["description", "member_count", "follower_count", "owner_id"], - expansions: ["owner_id"], - userFields: ["username", "verified"], -}); - -console.log(response.data); -console.log(response.includes); // Contains owner user object -``` - - - -### Response with expansion - -```json -{ - "data": { - "id": "84839422", - "name": "Tech News", - "description": "Top tech journalists", - "member_count": 50, - "follower_count": 1250, - "owner_id": "2244994945" - }, - "includes": { - "users": [ - { - "id": "2244994945", - "username": "XDevelopers", - "verified": true - } - ] - } -} -``` - - - Learn more about customizing responses - - ---- - -## Pagination - -When retrieving owned Lists, results are paginated: - - - -```bash cURL -# First request -curl "https://api.x.com/2/users/123/owned_lists?max_results=100" \ - -H "Authorization: Bearer $BEARER_TOKEN" - -# Subsequent request with pagination token -curl "https://api.x.com/2/users/123/owned_lists?max_results=100&pagination_token=NEXT_TOKEN" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# The SDK handles pagination automatically -all_lists = [] - -for page in client.lists.get_user_owned_lists(user_id="123", max_results=100): - if page.data: - all_lists.extend(page.data) - -print(f"Found {len(all_lists)} lists") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -async function getAllOwnedLists(userId) { - const allLists = []; - - // The SDK handles pagination automatically - const paginator = client.lists.getUserOwnedLists(userId, { maxResults: 100 }); - - for await (const page of paginator) { - if (page.data) { - allLists.push(...page.data); - } - } - - return allLists; -} - -// Usage -const lists = await getAllOwnedLists("123"); -console.log(`Found ${lists.length} lists`); -``` - - - - - Learn more about pagination - - ---- - -## Private Lists - -- Private Lists are only visible to the owner -- You must authenticate as the owner to retrieve private List details -- The `private` field indicates whether a List is private - ---- - -## Error handling - -| Status | Error | Solution | -|:-------|:------|:---------| -| 400 | Invalid request | Check List ID format | -| 401 | Unauthorized | Verify authentication | -| 403 | Forbidden | List may be private | -| 404 | Not Found | List doesn't exist | -| 429 | Too Many Requests | Wait and retry | - ---- - -## Next steps - - - - Make your first List lookup request - - - Get Posts from a List - - - Full endpoint documentation - - - Working code examples - - +--- +title: Integration Guide +sidebarTitle: Integration Guide +keywords: ["list lookup integration", "lists integration guide", "list lookup implementation"] +--- + +import { Button } from '/snippets/button.mdx'; + +This guide covers the key concepts you need to integrate the List lookup endpoints into your application. + +--- + +## Authentication + +List lookup endpoints support multiple authentication methods: + +| Method | Best for | Access to private Lists? | +|:-------|:---------|:-------------------------| +| [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) | Public List data | No | +| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | User-facing apps | Yes (owned/followed) | +| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy integrations | Yes (owned/followed) | + +### Example request + + + +```bash cURL +curl "https://api.x.com/2/lists/84839422?\ +list.fields=description,member_count,follower_count,private" \ + -H "Authorization: Bearer $BEARER_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_BEARER_TOKEN") + +# Get a List by ID +response = client.lists.get( + list_id="84839422", + list_fields=["description", "member_count", "follower_count", "private"] +) +print(response.data) +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); + +const response = await client.lists.get("84839422", { + listFields: ["description", "member_count", "follower_count", "private"], +}); +console.log(response.data); +``` + + + +--- + +## Endpoints overview + +| Method | Endpoint | Description | +|:-------|:---------|:------------| +| GET | [`/2/lists/:id`](/x-api/lists/get-list) | Get List by ID | +| GET | [`/2/users/:id/owned_lists`](/x-api/users/get-owned-lists) | Get Lists owned by a user | + +--- + +## Fields and expansions + +### Default response + +```json +{ + "data": { + "id": "84839422", + "name": "Tech News" + } +} +``` + +### Available fields + + +| Field | Description | +|:------|:------------| +| `created_at` | List creation timestamp | +| `description` | List description | +| `follower_count` | Number of followers | +| `member_count` | Number of members | +| `owner_id` | Owner's user ID | +| `private` | Whether List is private | + + + +| Field | Description | +|:------|:------------| +| `username` | Owner's @handle | +| `name` | Owner's display name | +| `verified` | Owner's verification status | +| `profile_image_url` | Owner's avatar URL | + + +### Example with expansions + + + +```bash cURL +curl "https://api.x.com/2/lists/84839422?\ +list.fields=description,member_count,follower_count,owner_id&\ +expansions=owner_id&\ +user.fields=username,verified" \ + -H "Authorization: Bearer $BEARER_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_BEARER_TOKEN") + +# Get List with owner expansion +response = client.lists.get( + list_id="84839422", + list_fields=["description", "member_count", "follower_count", "owner_id"], + expansions=["owner_id"], + user_fields=["username", "verified"] +) + +print(response.data) +print(response.includes) # Contains owner user object +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); + +const response = await client.lists.get("84839422", { + listFields: ["description", "member_count", "follower_count", "owner_id"], + expansions: ["owner_id"], + userFields: ["username", "verified"], +}); + +console.log(response.data); +console.log(response.includes); // Contains owner user object +``` + + + +### Response with expansion + +```json +{ + "data": { + "id": "84839422", + "name": "Tech News", + "description": "Top tech journalists", + "member_count": 50, + "follower_count": 1250, + "owner_id": "2244994945" + }, + "includes": { + "users": [ + { + "id": "2244994945", + "username": "XDevelopers", + "verified": true + } + ] + } +} +``` + + + Learn more about customizing responses + + +--- + +## Pagination + +When retrieving owned Lists, results are paginated: + + + +```bash cURL +# First request +curl "https://api.x.com/2/users/123/owned_lists?max_results=100" \ + -H "Authorization: Bearer $BEARER_TOKEN" + +# Subsequent request with pagination token +curl "https://api.x.com/2/users/123/owned_lists?max_results=100&pagination_token=NEXT_TOKEN" \ + -H "Authorization: Bearer $BEARER_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_BEARER_TOKEN") + +# The SDK handles pagination automatically +all_lists = [] + +for page in client.lists.get_user_owned_lists(user_id="123", max_results=100): + if page.data: + all_lists.extend(page.data) + +print(f"Found {len(all_lists)} lists") +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); + +async function getAllOwnedLists(userId) { + const allLists = []; + + // The SDK handles pagination automatically + const paginator = client.lists.getUserOwnedLists(userId, { maxResults: 100 }); + + for await (const page of paginator) { + if (page.data) { + allLists.push(...page.data); + } + } + + return allLists; +} + +// Usage +const lists = await getAllOwnedLists("123"); +console.log(`Found ${lists.length} lists`); +``` + + + + + Learn more about pagination + + +--- + +## Private Lists + +- Private Lists are only visible to the owner +- You must authenticate as the owner to retrieve private List details +- The `private` field indicates whether a List is private + +--- + +## Error handling + +| Status | Error | Solution | +|:-------|:------|:---------| +| 400 | Invalid request | Check List ID format | +| 401 | Unauthorized | Verify authentication | +| 403 | Forbidden | List may be private | +| 404 | Not Found | List doesn't exist | +| 429 | Too Many Requests | Wait and retry | + +--- + +## Next steps + + + + Make your first List lookup request + + + Get Posts from a List + + + Full endpoint documentation + + + Working code examples + + diff --git a/x-api/lists/list-lookup/migrate/overview.mdx b/x-api/lists/list-lookup/migrate/overview.mdx index b2a471a00..14cbd6848 100644 --- a/x-api/lists/list-lookup/migrate/overview.mdx +++ b/x-api/lists/list-lookup/migrate/overview.mdx @@ -1,51 +1,51 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["list lookup migration", "lists lookup migration", "v1.1 to v2 list lookup", "list lookup migration guide", "migrate list lookup"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing X API’s List lookup endpoints - -The v2 List lookup endpoint group will replace the standard v1.1 [GET lists/show](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-show) and  [GET lists/ownership](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships) endpoints. If you have code, apps, or tools that use one of these versions of the List lookup endpoints, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you. - -The following tables compare the standard v1.1 and X API v2 List endpoints: - -**List Lookup by ID** - -| | | | -| :--- | :--- | :--- | -| Description | Standard v1.1 | X API v2 | -| HTTP methods supported | `GET` | `GET` | -| Host domain | `https://api.x.com` | `https://api.x.com` | -| Endpoint path | `/1.1/lists/show.json` | `/2/lists/:id` | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min with OAuth 1.0a

75 requests per 15min with OAuth 2.0

75 requests per 15 min with App only | 75 requests per 15 min with OAuth 1.0a

75 requests per 15 min with OAuth 2.0

75 requests per 15 min with App only | - -**User owned List lookup** - -| | | | -| :--- | :--- | :--- | -| Description | Standard v1.1 | X API v2 | -| HTTP methods supported | `GET` | `GET` | -| Host domain | `https://api.x.com` | `https://api.x.com` | -| Endpoint path | `/1.1/lists/ownerships.json` | `/2/users/:id/owned_lists` | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 15 requests per 15 min with OAuth 1.0a

15 requests per 15 min with App only | 15 requests per 15 min with OAuth 1.0a

15 requests per 15min with OAuth 2.0

15 requests per 15 min with App only | - -To access the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info). When authenticating, you must use keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  - -Learn more about getting access to the X API v2 endpoints in our [getting started](/x-api/getting-started/getting-access) page. - -
- - - -
+--- +title: Overview +sidebarTitle: Overview +keywords: ["list lookup migration", "lists lookup migration", "v1.1 to v2 list lookup", "list lookup migration guide", "migrate list lookup"] + + +import { Button } from '/snippets/button.mdx'; + +## Comparing X API’s List lookup endpoints + +The v2 List lookup endpoint group will replace the standard v1.1 [GET lists/show](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-show) and  [GET lists/ownership](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships) endpoints. If you have code, apps, or tools that use one of these versions of the List lookup endpoints, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you. + +The following tables compare the standard v1.1 and X API v2 List endpoints: + +**List Lookup by ID** + +| | | | +| :--- | :--- | :--- | +| Description | Standard v1.1 | X API v2 | +| HTTP methods supported | `GET` | `GET` | +| Host domain | `https://api.x.com` | `https://api.x.com` | +| Endpoint path | `/1.1/lists/show.json` | `/2/lists/:id` | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min with OAuth 1.0a

75 requests per 15min with OAuth 2.0

75 requests per 15 min with App only | 75 requests per 15 min with OAuth 1.0a

75 requests per 15 min with OAuth 2.0

75 requests per 15 min with App only | + +**User owned List lookup** + +| | | | +| :--- | :--- | :--- | +| Description | Standard v1.1 | X API v2 | +| HTTP methods supported | `GET` | `GET` | +| Host domain | `https://api.x.com` | `https://api.x.com` | +| Endpoint path | `/1.1/lists/ownerships.json` | `/2/users/:id/owned_lists` | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 15 requests per 15 min with OAuth 1.0a

15 requests per 15 min with App only | 15 requests per 15 min with OAuth 1.0a

15 requests per 15min with OAuth 2.0

15 requests per 15 min with App only | + +To access the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info). When authenticating, you must use keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  + +Learn more about getting access to the X API v2 endpoints in our [getting started](/x-api/getting-started/getting-access) page. + +
+ + + +
diff --git a/x-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx b/x-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx index ec9bad1d6..7268d4fc4 100644 --- a/x-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx @@ -1,129 +1,129 @@ ---- -title: v1 to v2 -sidebarTitle: v1 to v2 -keywords: ["v1.1 to v2 migration", "list lookup migration", "migrate list lookup", "standard to v2 list lookup", "v1 to v2 list lookup", "migration guide"] ---- - -import { Button } from '/snippets/button.mdx'; - -### List lookup: Standard v1.1 compared to X API v2 - - -If you have been working with the standard v1.1 [GET lists/show](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-show) and  [GET lists/ownerships](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 List lookup endpoints. - -* **Similarities** - * Authentication methods - * Rate limits -* **Differences** - * Endpoint URLs - * App and Project requirements - * Data objects per request limits - * Response data formats - * Request parameters - -#### Similarities - -**Authentication** - -Both endpoint versions support both [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2) and [App only](/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token). Therefore, if you were previously using one of the standard v1.1 List lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see [this App only guide](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token). - -**Rate limits** - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| /1.1/lists/show.json

75 requests per 15-minute window with OAuth 1.0a User Context

75 requests per 15-minute window with App only | /2/lists/:id

75 requests per 15-minute window with OAuth 1.0a User Context

75 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | -| /1.1/lists/ownerships.json

15 requests per 15-minute window with OAuth 1.0a User Context

15 requests per 15-minute window with App only | /2/users/:id/owned_lists

15 requests per 15-minute window with OAuth 1.0a User Context

15 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE

15 requests per 15-minute window with App only | - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * GET https://api.x.com/1.1/lists/show.json - (Lookup a specified List) - * GET https://api.x.com/1.1/lists/ownerships.json - (Lookup specified user owned Lists) -* X API v2 endpoint: - * GET https://api.x.com/2/lists/:id - (Lookup a specified List) - - * GET https://api.x.com/2/users/:id/owned_lists - (Lookup specified user owned Lists) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - -**Data objects per request limits** - -The standard v1.1 /lists/ownerships endpoint allows you to return up to 1000 Lists per request. The new v2 endpoints allow you to return up to 100 Lists per request. By default, 100 user objects will be returned, to change the number of results you will need to pass a query parameter max_results= with a number between 1-100; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request. - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default and then have the option to use parameters to identify which additional fields or sets of fields should return in the payload. - -The X API v2 version only delivers the List id and name fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any List fields that you request from this endpoint will return in the primary List object. Any expanded Post or user object and fields will return an includes object within your response. You can then match any expanded objects back to the List object by matching the IDs located in both the user and the expanded Post object.  - -Here are examples of possible List fields and expansions: - -* created_at - -* follower_count - -* member_count - -* owner_id - -* description - -* private - - -| | | -| :--- | :--- | -| **Endpoint** | **Expansion** | -| /2/lists/:id | owner_id | -| /2/users/:id/owned_lists | owner_id | - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration) that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you with the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  - -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  - -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  - -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values. - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -**List lookup by ID** - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| list_id | id | -| slug | No equivalent | -| owner\_screen\_name | No equivalent | -| owner_id | Requested with expansions/fields parameter | - -**User owned List lookup** - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| user_id | id | -| screen_name | No equivalent | -| count | max_results | +--- +title: v1 to v2 +sidebarTitle: v1 to v2 +keywords: ["v1.1 to v2 migration", "list lookup migration", "migrate list lookup", "standard to v2 list lookup", "v1 to v2 list lookup", "migration guide"] + + +import { Button } from '/snippets/button.mdx'; + +### List lookup: Standard v1.1 compared to X API v2 + + +If you have been working with the standard v1.1 [GET lists/show](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-show) and  [GET lists/ownerships](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 List lookup endpoints. + +* **Similarities** + * Authentication methods + * Rate limits +* **Differences** + * Endpoint URLs + * App and Project requirements + * Data objects per request limits + * Response data formats + * Request parameters + +#### Similarities + +**Authentication** + +Both endpoint versions support both [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2) and [App only](/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token). Therefore, if you were previously using one of the standard v1.1 List lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see [this App only guide](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token). + +**Rate limits** + +| | | +| :--- | :--- | +| **Standard v1.1** | **X API v2** | +| /1.1/lists/show.json

75 requests per 15-minute window with OAuth 1.0a User Context

75 requests per 15-minute window with App only | /2/lists/:id

75 requests per 15-minute window with OAuth 1.0a User Context

75 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | +| /1.1/lists/ownerships.json

15 requests per 15-minute window with OAuth 1.0a User Context

15 requests per 15-minute window with App only | /2/users/:id/owned_lists

15 requests per 15-minute window with OAuth 1.0a User Context

15 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE

15 requests per 15-minute window with App only | + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * GET https://api.x.com/1.1/lists/show.json + (Lookup a specified List) + * GET https://api.x.com/1.1/lists/ownerships.json + (Lookup specified user owned Lists) +* X API v2 endpoint: + * GET https://api.x.com/2/lists/:id + (Lookup a specified List) + + * GET https://api.x.com/2/users/:id/owned_lists + (Lookup specified user owned Lists) + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. + +**Data objects per request limits** + +The standard v1.1 /lists/ownerships endpoint allows you to return up to 1000 Lists per request. The new v2 endpoints allow you to return up to 100 Lists per request. By default, 100 user objects will be returned, to change the number of results you will need to pass a query parameter max_results= with a number between 1-100; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request. + +**Response data format** + +One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. + +For the standard endpoints, you receive many of the response fields by default and then have the option to use parameters to identify which additional fields or sets of fields should return in the payload. + +The X API v2 version only delivers the List id and name fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any List fields that you request from this endpoint will return in the primary List object. Any expanded Post or user object and fields will return an includes object within your response. You can then match any expanded objects back to the List object by matching the IDs located in both the user and the expanded Post object.  + +Here are examples of possible List fields and expansions: + +* created_at + +* follower_count + +* member_count + +* owner_id + +* description + +* private + + +| | | +| :--- | :--- | +| **Endpoint** | **Expansion** | +| /2/lists/:id | owner_id | +| /2/users/:id/owned_lists | owner_id | + +We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  + +We have also put together a [data format migration guide](/x-api/migrate/data-format-migration) that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you with the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  + +In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. + +* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  + +* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  + +* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  + +* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values. + +**Request parameters** + +The following standard v1.1 request parameters have equivalents in X API v2: + +**List lookup by ID** + +| | | +| :--- | :--- | +| **Standard v1.1** | **X API v2** | +| list_id | id | +| slug | No equivalent | +| owner\_screen\_name | No equivalent | +| owner_id | Requested with expansions/fields parameter | + +**User owned List lookup** + +| | | +| :--- | :--- | +| **Standard v1.1** | **X API v2** | +| user_id | id | +| screen_name | No equivalent | +| count | max_results | | cursor | pagination_token | \ No newline at end of file diff --git a/x-api/lists/list-members/integrate.mdx b/x-api/lists/list-members/integrate.mdx index 4e57950c8..456d48071 100644 --- a/x-api/lists/list-members/integrate.mdx +++ b/x-api/lists/list-members/integrate.mdx @@ -1,85 +1,85 @@ ---- -title: Integration guide -sidebarTitle: Integration guide -keywords: ["list members integration", "list members guide", "list members setup", "list membership integration", "list members integration guide"] ---- - -import { Button } from '/snippets/button.mdx'; - -This page covers tools and key concepts for integrating the List members endpoints. - ---- - -## Helpful tools - -Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: - -### Postman - -Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. - -### Code samples - -Are you interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). - -### Third-party libraries - -Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. - ---- - -## Key concepts - -### Authentication - -All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context, OAuth 2.0 Authorization Code with PKCE, or App only to authenticate your requests for the Lists **lookup** endpoints. However, you must authenticate with OAuth 1.0a User Context or OAuth 2.0 for the **manage** Lists endpoints. - -[OAuth 1.0a User Context](/resources/fundamentals/authentication), which means that you must use a set of API Keys and user Access Tokens to make a successful request. The access tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the [3-legged OAuth flow](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). - -Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries), use a tool like Postman, or use either OAuth 2.0 or App only to authenticate your requests. - -[OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) allows for greater control over an application's scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. - -To enable OAuth 2.0 in your App, you must enable it in your's App's authentication settings found in the App settings section of the Developer Console. - -[App only](/resources/fundamentals/authentication#oauth-2-0) just requires that you pass an [App only Access Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only) with your request. You can either generate an App only Access Token directly within a developer App, or generate one using the [POST oauth2/token](/resources/fundamentals/authentication#post-oauth2-token) endpoint. - -### Developer Console, Projects, and developer Apps - -To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. - -### Rate limits - -Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests you can make on behalf of your app or on behalf of an authenticated user. - -Lookup (GET) endpoints are rate limited at both the App-level and the user-level; while manage (POST/DELETE) endpoints are limited at the user-level. The app rate limit means that you, the developer, can only make a certain number of requests to this endpoint over a given period of time from any given App (assumed by using either the API Key and API Secret Key, or the App only Access Token). The user rate limit means that the authenticated user that you are making the request on behalf of can only perform a List lookup a certain number of times across any developer App. - -The chart below shows the rate limits for each endpoint. - -| Endpoint | HTTP method | Rate limit | -| :--- | :--- | :--- | -| /2/lists/:id/members | GET | 900 requests per 15 minutes | -| /2/users/:id/list_memberships | GET | 75 requests per 15 minutes | -| /2/lists/:id/members | POST | 300 requests per 15 minutes | -| /2/lists/:id/members/:user_id | DELETE | 300 requests per 15 minutes | - -### Fields and expansions - -The X API v2 GET endpoint allows users to select exactly which data they want to return from the API using a set of tools called `fields` and `expansions`. The `expansions` parameter allows you to expand objects referenced in the payload. For example, looking up List members allows you to pull the following [expansions](/x-api/fundamentals/expansions): - -* `pinned_tweet_id` - -The `fields` parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. List members lookup delivers user objects primarily. By default, the user object returns id, name, and username fields. To receive additional fields such as `user.created_at` or `user.description`, you will have to specifically request those using a user.fields parameter. - -We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -The chart below shows the field and expansions available for each lookup endpoint: - -| Endpoint | Fields | Expansions | -| :--- | :--- | :--- | -| /2/lists/:id/members | `user.fields`, `tweet.fields` | `pinned_tweet_id` | -| /2/users/:id/list_memberships | `list.fields`, `user.fields` | `owner_id` | - -### Pagination - -Looking up membership/members can return a lot of data. To ensure we are returning consistent, high-performing results at any given time, we use pagination. Pagination is a feature in X API v2 endpoints that return more results than can be returned in a single response. When that happens, the data is returned in a series of 'pages'. Learn more about how to [paginate through results.](/x-api/fundamentals/pagination) +--- +title: Integration guide +sidebarTitle: Integration guide +keywords: ["list members integration", "list members guide", "list members setup", "list membership integration", "list members integration guide"] + + +--- + +import { Button } from '/snippets/button.mdx'; + +This page covers tools and key concepts for integrating the List members endpoints. + +## Helpful tools + +Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: + +### Postman + +Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. + +### Code samples + +Are you interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). + +### Third-party libraries + +Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. + +--- + +## Key concepts + +### Authentication + +All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context, OAuth 2.0 Authorization Code with PKCE, or App only to authenticate your requests for the Lists **lookup** endpoints. However, you must authenticate with OAuth 1.0a User Context or OAuth 2.0 for the **manage** Lists endpoints. + +[OAuth 1.0a User Context](/resources/fundamentals/authentication), which means that you must use a set of API Keys and user Access Tokens to make a successful request. The access tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the [3-legged OAuth flow](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). + +Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries), use a tool like Postman, or use either OAuth 2.0 or App only to authenticate your requests. + +[OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) allows for greater control over an application's scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. + +To enable OAuth 2.0 in your App, you must enable it in your's App's authentication settings found in the App settings section of the Developer Console. + +[App only](/resources/fundamentals/authentication#oauth-2-0) just requires that you pass an [App only Access Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only) with your request. You can either generate an App only Access Token directly within a developer App, or generate one using the [POST oauth2/token](/resources/fundamentals/authentication#post-oauth2-token) endpoint. + +### Developer Console, Projects, and developer Apps + +To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. + +### Rate limits + +Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests you can make on behalf of your app or on behalf of an authenticated user. + +Lookup (GET) endpoints are rate limited at both the App-level and the user-level; while manage (POST/DELETE) endpoints are limited at the user-level. The app rate limit means that you, the developer, can only make a certain number of requests to this endpoint over a given period of time from any given App (assumed by using either the API Key and API Secret Key, or the App only Access Token). The user rate limit means that the authenticated user that you are making the request on behalf of can only perform a List lookup a certain number of times across any developer App. + +The chart below shows the rate limits for each endpoint. + +| Endpoint | HTTP method | Rate limit | +| :--- | :--- | :--- | +| /2/lists/:id/members | GET | 900 requests per 15 minutes | +| /2/users/:id/list_memberships | GET | 75 requests per 15 minutes | +| /2/lists/:id/members | POST | 300 requests per 15 minutes | +| /2/lists/:id/members/:user_id | DELETE | 300 requests per 15 minutes | + +### Fields and expansions + +The X API v2 GET endpoint allows users to select exactly which data they want to return from the API using a set of tools called `fields` and `expansions`. The `expansions` parameter allows you to expand objects referenced in the payload. For example, looking up List members allows you to pull the following [expansions](/x-api/fundamentals/expansions): + +* `pinned_tweet_id` + +The `fields` parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. List members lookup delivers user objects primarily. By default, the user object returns id, name, and username fields. To receive additional fields such as `user.created_at` or `user.description`, you will have to specifically request those using a user.fields parameter. + +We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). + +The chart below shows the field and expansions available for each lookup endpoint: + +| Endpoint | Fields | Expansions | +| :--- | :--- | :--- | +| /2/lists/:id/members | `user.fields`, `tweet.fields` | `pinned_tweet_id` | +| /2/users/:id/list_memberships | `list.fields`, `user.fields` | `owner_id` | + +### Pagination + +Looking up membership/members can return a lot of data. To ensure we are returning consistent, high-performing results at any given time, we use pagination. Pagination is a feature in X API v2 endpoints that return more results than can be returned in a single response. When that happens, the data is returned in a series of 'pages'. Learn more about how to [paginate through results.](/x-api/fundamentals/pagination) diff --git a/x-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx b/x-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx index 85c5d6aeb..9648e8b1b 100644 --- a/x-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx +++ b/x-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx @@ -1,137 +1,40 @@ ---- -title: List members lookup -sidebarTitle: List members lookup -keywords: ["list members lookup migration", "v1.1 to v2 list members lookup", "migrate list members lookup", "standard to v2 list members", "list members migration"] ---- - -import { Button } from '/snippets/button.mdx'; - -### List members lookup: Standard v1.1 compared to X API v2 - - -If you have been working with the standard v1.1 [GET lists/members](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-members) and [GET lists/memberships](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 List member endpoints. - -* **Similarities** - * Authentication methods -* **Differences** - * Endpoint URLs - * Rate limits - * App and Project requirements - * Data objects per request limits - * Response data formats - * Request parameters - -#### Similarities - -**Authentication** - -Both endpoint versions support both [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2) and [App only](/resources/fundamentals/authentication#oauth-2-0). Therefore, if you were previously using one of the standard v1.1 List members endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see [this App only guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * GET https://api.x.com/1.1/lists/members.json - (Lookup members of a specified List) - * GET https://api.x.com/1.1/lists/memberships.json - (Lookup Lists a user is a member of) -* X API v2 endpoint: - * GET https://api.x.com/2/lists/:id/members - (Lookup members of a specified List) - - * GET https://api.x.com/2/users/:id/list_memberships - (Lookup Lists a user is a member of) - -**Rate limits** - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| /1.1/lists/members.json

900 requests per 15-minute window with OAuth 1.0a User Context

15 requests per 15-minute window with App only | /2/lists/:id/members

900 requests per 15-minute window with OAuth 1.0a User Context

900 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE

900 requests per 15-minute window with App only | -| /1.1/lists/memberships.json

15 requests per 15-minute window with OAuth 1.0a User Context

15 requests per 15-minute window with App only | /2/users/:id/list_memberships

15 requests per 15-minute window with OAuth 1.0a User Context

15 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE

15 requests per 15-minute window with App only | - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - -**Data objects per request limits** - -The standard v1.1 /1.1/lists/members endpoint allows you to return up to 5000 users per request. The new v2 endpoints allow you to return up to 100 users per request. By default, 100 user objects will be returned, to change the number of results you will need to pass a query parameter max_results= with a number between 1-100; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request. - - Additionally, the endpoint /1.1/lists/memberships, allow you to return up to 1000 Lists per request. With the v2 replacement, the endpoint allows up to 100 Lists per request. By default 100 Lists objects are returned, use the query parameters max_results= and pagination_token in the same fashion as /1.1/lists/members to change the number of results. - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default and then have the option to use parameters to identify which additional fields or sets of fields should return in the payload. - -The X API v2 version /users/:id/list_memberships will deliver the List id and name fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any List fields that you request from this endpoint will return in the primary List object. Any expanded object and fields will return an includes object within your response. You can then match any expanded objects back to the primary List object by matching the IDs located in both the primary and the expanded object.  - -Here are examples of possible List fields and expansions: - -* created_at - -* follower_count - -* member_count - -* owner_id - -* description - -* private - - -| | | -| :--- | :--- | -| **Endpoint** | **Expansion** | -| /2/lists/:id/members | pinned\_tweet\_id | -| /2/users/:id/list_memberships | owner_id | - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration) that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you with the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  - -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  - -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  - -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values. - - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -**List members lookup** - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| list_id | id | -| slug | No equivalent | -| owner\_screen\_name | No equivalent | -| owner_id | No equivalent | -| count | max_results | -| cursor | pagination_token | -| include_entities | No equivalent | -| skip_status | No equivalent | - -**List membership lookup** - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| user_id | id | -| screen_name | No equivalent | -| count | max_results | -| cursor | pagination_token | - +--- +title: List members lookup +sidebarTitle: List members lookup +keywords: ["list members lookup migration", "v1.1 to v2 list members lookup", "migrate list members lookup", "standard to v2 list members", "list members migration"] + + +--- +import { Button } from '/snippets/button.mdx'; + +### List members lookup: Standard v1.1 compared to X API v2 + + +If you have been working with the standard v1.1 [GET lists/members](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-members) and [GET lists/memberships](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 List member endpoints. + +* **Similarities** + * Authentication methods +* **Differences** + * Endpoint URLs + * Rate limits + * App and Project requirements + * Data objects per request limits + * Response data formats + * Request parameters + +#### Similarities + +**Authentication** + +Both endpoint versions support both [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2) and [App only](/resources/fundamentals/authentication#oauth-2-0). Therefore, if you were previously using one of the standard v1.1 List members endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see [this App only guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * GET https://api.x.com/1.1/lists/members.json + (Lookup members of a specified List) + * GET https://api.x.com/1.1/lists/mem \ No newline at end of file diff --git a/x-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.mdx b/x-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.mdx index ef3d1984e..6768407fa 100644 --- a/x-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.mdx +++ b/x-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.mdx @@ -1,65 +1,65 @@ ---- -title: Manage list members -sidebarTitle: Manage list members -keywords: ["manage list members migration", "v1.1 to v2 manage list members", "migrate manage list members", "standard to v2 list members", "list members migration"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Manage List members: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST lists/members/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create) and [POST lists/members/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage List members endpoints. - -* **Similarities** - * Authentication -* **Differences** - * Endpoint URLs - * App and Project requirements - * HTTP methods - * Rate limits - * Request parameters - -#### Similarities - -**Authentication** - -Both endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage List member endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/lists/members/create.json - (Adds a member to a specified List) - * POST https://api.x.com/1.1/lists/members/destroy.json - (Removes a member from a specified List) -* X API v2 endpoint: - * POST https://api.x.com/2/lists/:id/members - (Adds a member to a specified List) - - * DELETE https://api.x.com/2/lists/:id/members/:user_id - (Removes a member from a specified List) - -**Rate limits** - -| **Standard v1.1** | **X API v2** | -| :--- | :--- | -| /1.1/lists/members/create.json

none | /2/lists/:id/members

300 requests per 15-minute window with OAuth 1.0a User Context

300 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | -| /1.1/lists/members/destroy.json

none | /2/lists/:id/members/:user_id

300 requests per 15-minute window with OAuth 1.0a User Context

300 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps related to a project. - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| **Standard v1.1** | **X API v2** | -| :--- | :--- | -| list_id | id | -| slug | No equivalent | -| screen_name | No equivalent | -| owner\_screen\_name | No equivalent | -| owner_id | No equivalent | +--- +title: Manage list members +sidebarTitle: Manage list members +keywords: ["manage list members migration", "v1.1 to v2 manage list members", "migrate manage list members", "standard to v2 list members", "list members migration"] + + +import { Button } from '/snippets/button.mdx'; + +### Manage List members: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST lists/members/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create) and [POST lists/members/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage List members endpoints. + +* **Similarities** + * Authentication +* **Differences** + * Endpoint URLs + * App and Project requirements + * HTTP methods + * Rate limits + * Request parameters + +#### Similarities + +**Authentication** + +Both endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage List member endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/lists/members/create.json + (Adds a member to a specified List) + * POST https://api.x.com/1.1/lists/members/destroy.json + (Removes a member from a specified List) +* X API v2 endpoint: + * POST https://api.x.com/2/lists/:id/members + (Adds a member to a specified List) + + * DELETE https://api.x.com/2/lists/:id/members/:user_id + (Removes a member from a specified List) + +**Rate limits** + +| **Standard v1.1** | **X API v2** | +| :--- | :--- | +| /1.1/lists/members/create.json

none | /2/lists/:id/members

300 requests per 15-minute window with OAuth 1.0a User Context

300 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | +| /1.1/lists/members/destroy.json

none | /2/lists/:id/members/:user_id

300 requests per 15-minute window with OAuth 1.0a User Context

300 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE | + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps related to a project. + +**Request parameters** + +The following standard v1.1 request parameters have equivalents in X API v2: + +| **Standard v1.1** | **X API v2** | +| :--- | :--- | +| list_id | id | +| slug | No equivalent | +| screen_name | No equivalent | +| owner\_screen\_name | No equivalent | +| owner_id | No equivalent | diff --git a/x-api/lists/list-members/migrate/overview.mdx b/x-api/lists/list-members/migrate/overview.mdx index 42a532ee6..e511b0fe2 100644 --- a/x-api/lists/list-members/migrate/overview.mdx +++ b/x-api/lists/list-members/migrate/overview.mdx @@ -1,81 +1,81 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["list members migration", "list members migrate", "v1.1 to v2 list members", "list members migration guide", "migrate list members"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing X API’s List members endpoints - - -The v2 List members endpoint group will replace the standard v1.1 [GET lists/members](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-members), [GET lists/memberships](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships), [POST lists/members/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create) and [POST lists/members/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy) endpoints. If you have code, apps, or tools that use one of these versions of the List member endpoints, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you.  - -### List members lookup - -The v2 List members lookup endpoints will replace the standard  [GET lists/members](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-members), [GET lists/memberships](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships), endpoints. - -The following tables compare the standard v1.1 and X API v2 List endpoints: - -**List member Lookup** - -| | | | -| :--- | :--- | :--- | -| Description | Standard v1.1 | X API v2 | -| HTTP methods supported | `GET` | `GET` | -| Host domain | `https://api.x.com` | `https://api.x.com` | -| Endpoint path | `/1.1/lists/members.json` | `/2/lists/:id/members` | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 900 requests per 15 min with OAuth 1.0a

75 requests per 15min with App only | 900 requests per 15 min with OAuth 1.0a

900 requests per 15 min with OAuth 2.0

900 requests per 15 min with App only | - -**List membership lookup** - -| | | | -| :--- | :--- | :--- | -| Description | Standard v1.1 | X API v2 | -| HTTP methods supported | `GET` | `GET` | -| Host domain | `https://api.x.com` | `https://api.x.com` | -| Endpoint path | `/1.1/lists/memberships.json` | `/2/users/:id/list_memberships` | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min with OAuth 1.0a

75 requests per 15min with App only | 75 requests per 15 min with OAuth 1.0a

75 requests per 15 min with OAuth 2.0

75 requests per 15min with App only | - -### Manage List members - -The v2 manage List members endpoints will replace the standard [POST lists/members/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create), [POST lists/members/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy) endpoints. - -The following tables compare the standard v1.1 and X API v2 List endpoints: - -**Add member** - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | POST | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/lists/members/create.json | /2/lists/:id/members | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | -| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | - -**Remove member** - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | DELETE | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/lists/members/destroy.json | /2/lists/:id/:user_id | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | -| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | - -To access the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info). When authenticating, you must use keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  - -Learn more about getting access to the X API v2 endpoints in our [getting started](/x-api/getting-started/getting-access) page. -
- - - +--- +title: Overview +sidebarTitle: Overview +keywords: ["list members migration", "list members migrate", "v1.1 to v2 list members", "list members migration guide", "migrate list members"] + + +import { Button } from '/snippets/button.mdx'; + +## Comparing X API’s List members endpoints + + +The v2 List members endpoint group will replace the standard v1.1 [GET lists/members](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-members), [GET lists/memberships](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships), [POST lists/members/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create) and [POST lists/members/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy) endpoints. If you have code, apps, or tools that use one of these versions of the List member endpoints, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you.  + +### List members lookup + +The v2 List members lookup endpoints will replace the standard  [GET lists/members](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-members), [GET lists/memberships](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships), endpoints. + +The following tables compare the standard v1.1 and X API v2 List endpoints: + +**List member Lookup** + +| | | | +| :--- | :--- | :--- | +| Description | Standard v1.1 | X API v2 | +| HTTP methods supported | `GET` | `GET` | +| Host domain | `https://api.x.com` | `https://api.x.com` | +| Endpoint path | `/1.1/lists/members.json` | `/2/lists/:id/members` | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 900 requests per 15 min with OAuth 1.0a

75 requests per 15min with App only | 900 requests per 15 min with OAuth 1.0a

900 requests per 15 min with OAuth 2.0

900 requests per 15 min with App only | + +**List membership lookup** + +| | | | +| :--- | :--- | :--- | +| Description | Standard v1.1 | X API v2 | +| HTTP methods supported | `GET` | `GET` | +| Host domain | `https://api.x.com` | `https://api.x.com` | +| Endpoint path | `/1.1/lists/memberships.json` | `/2/users/:id/list_memberships` | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min with OAuth 1.0a

75 requests per 15min with App only | 75 requests per 15 min with OAuth 1.0a

75 requests per 15 min with OAuth 2.0

75 requests per 15min with App only | + +### Manage List members + +The v2 manage List members endpoints will replace the standard [POST lists/members/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create), [POST lists/members/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy) endpoints. + +The following tables compare the standard v1.1 and X API v2 List endpoints: + +**Add member** + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | POST | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/lists/members/create.json | /2/lists/:id/members | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | +| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | + +**Remove member** + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | DELETE | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/lists/members/destroy.json | /2/lists/:id/:user_id | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | +| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | + +To access the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info). When authenticating, you must use keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  + +Learn more about getting access to the X API v2 endpoints in our [getting started](/x-api/getting-started/getting-access) page. +
+ + +
\ No newline at end of file diff --git a/x-api/lists/list-tweets/integrate.mdx b/x-api/lists/list-tweets/integrate.mdx index d2c4777e2..14e0c9c76 100644 --- a/x-api/lists/list-tweets/integrate.mdx +++ b/x-api/lists/list-tweets/integrate.mdx @@ -1,81 +1,81 @@ ---- -title: Integration guide -sidebarTitle: Integration guide -keywords: ["list tweets integration", "list timeline integration", "list tweets guide", "list timeline setup"] ---- - -import { Button } from '/snippets/button.mdx'; - -This page covers tools and key concepts for integrating the List Posts lookup endpoint. - ---- - -## Helpful tools - -Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: - -### Postman - -Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. - -### Code samples - -Are you interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). - -### Third-party libraries - -Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. - ---- - -## Key concepts - -### Authentication - -All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context, App only, or OAuth 2.0 Authorization Code with PKCE to authenticate your requests to this endpoint. - -[OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2), which means that you must use a set of API Keys and user Access Tokens to make a successful request. The access tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the [3-legged OAuth flow](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). - -Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries), use a tool like Postman, or use either OAuth 2.0 or App only to authenticate your requests. - -[OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) allows for greater control over an application's scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. - -To enable OAuth 2.0 in your App, you must enable it in your's App's authentication settings found in the App settings section of the Developer Console. - -[App only](/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token) just requires that you pass an [App only Access Token](/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token) with your request. You can either generate an App only Access Token directly within a developer App, or generate one using the [POST oauth2/token](/resources/fundamentals/authentication#post-oauth2-token) endpoint. - -### Developer Console, Projects, and developer Apps - -To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. - -### Rate limits - -Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](https://developer.x.com/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests you can make on behalf of your app or on behalf of an authenticated user. - -This endpoint is rate limited at both the App-level and the user-level. The app rate limit means that you, the developer, can only make a certain number of requests to this endpoint over a given period of time from any given App (assumed by using either the API Key and API Secret Key, or the Bearer Token). The user rate limit means that the authenticated user that you are making the request on behalf of can only perform a List Post lookup a certain number of times across any developer App. - -The chart below shows the rate limits for each endpoint. - -| Endpoint | HTTP method | Rate limit | -| :--- | :--- | :--- | -| /2/lists/:id/tweets | GET | 900 requests per 15 minutes | - -### Fields and expansions - -The X API v2 GET endpoint allows users to select exactly which data they want to return from the API using a set of tools called `fields` and `expansions`. The `expansions` parameter allows you to expand objects referenced in the payload. For example, looking up List Posts allows you to pull the following [expansions](/x-api/fundamentals/expansions): - -* `author_id` - -The `fields` parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. This endpoint delivers Post objects primarily. By default, the Post object returns the `id`, and `text` fields. To receive additional fields such as `tweet.created_at` or `tweet.lang`, you will have to specifically request those using a fields parameter. - -We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). - -The chart below shows the field and expansions available for the lookup endpoint: - -| Endpoint | Fields | Expansions | -| :--- | :--- | :--- | -| /2/lists/:id/tweets | `tweet.fields`, `user.fields` | `author_id` | - -### Pagination - -Looking up List Posts can return a lot of data. To ensure we are returning consistent, high-performing results at any given time, we use pagination. Pagination is a feature in X API v2 endpoints that return more results than can be returned in a single response. When that happens, the data is returned in a series of 'pages'. Learn more about how to [paginate through results.](/x-api/fundamentals/pagination) +--- +title: Integration guide +sidebarTitle: Integration guide +keywords: ["list tweets integration", "list timeline integration", "list tweets guide", "list timeline setup"] + + +--- + +import { Button } from '/snippets/button.mdx'; + +This page covers tools and key concepts for integrating the List Posts lookup endpoint. + +## Helpful tools + +Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: + +### Postman + +Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. + +### Code samples + +Are you interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). + +### Third-party libraries + +Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. + +--- + +## Key concepts + +### Authentication + +All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context, App only, or OAuth 2.0 Authorization Code with PKCE to authenticate your requests to this endpoint. + +[OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2), which means that you must use a set of API Keys and user Access Tokens to make a successful request. The access tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the [3-legged OAuth flow](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). + +Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries), use a tool like Postman, or use either OAuth 2.0 or App only to authenticate your requests. + +[OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) allows for greater control over an application's scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. + +To enable OAuth 2.0 in your App, you must enable it in your's App's authentication settings found in the App settings section of the Developer Console. + +[App only](/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token) just requires that you pass an [App only Access Token](/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token) with your request. You can either generate an App only Access Token directly within a developer App, or generate one using the [POST oauth2/token](/resources/fundamentals/authentication#post-oauth2-token) endpoint. + +### Developer Console, Projects, and developer Apps + +To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. + +### Rate limits + +Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](https://developer.x.com/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests you can make on behalf of your app or on behalf of an authenticated user. + +This endpoint is rate limited at both the App-level and the user-level. The app rate limit means that you, the developer, can only make a certain number of requests to this endpoint over a given period of time from any given App (assumed by using either the API Key and API Secret Key, or the Bearer Token). The user rate limit means that the authenticated user that you are making the request on behalf of can only perform a List Post lookup a certain number of times across any developer App. + +The chart below shows the rate limits for each endpoint. + +| Endpoint | HTTP method | Rate limit | +| :--- | :--- | :--- | +| /2/lists/:id/tweets | GET | 900 requests per 15 minutes | + +### Fields and expansions + +The X API v2 GET endpoint allows users to select exactly which data they want to return from the API using a set of tools called `fields` and `expansions`. The `expansions` parameter allows you to expand objects referenced in the payload. For example, looking up List Posts allows you to pull the following [expansions](/x-api/fundamentals/expansions): + +* `author_id` + +The `fields` parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. This endpoint delivers Post objects primarily. By default, the Post object returns the `id`, and `text` fields. To receive additional fields such as `tweet.created_at` or `tweet.lang`, you will have to specifically request those using a fields parameter. + +We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). + +The chart below shows the field and expansions available for the lookup endpoint: + +| Endpoint | Fields | Expansions | +| :--- | :--- | :--- | +| /2/lists/:id/tweets | `tweet.fields`, `user.fields` | `author_id` | + +### Pagination + +Looking up List Posts can return a lot of data. To ensure we are returning consistent, high-performing results at any given time, we use pagination. Pagination is a feature in X API v2 endpoints that return more results than can be returned in a single response. When that happens, the data is returned in a series of 'pages'. Learn more about how to [paginate through results.](/x-api/fundamentals/pagination) diff --git a/x-api/lists/list-tweets/migrate/overview.mdx b/x-api/lists/list-tweets/migrate/overview.mdx index c28adbfab..937256dc7 100644 --- a/x-api/lists/list-tweets/migrate/overview.mdx +++ b/x-api/lists/list-tweets/migrate/overview.mdx @@ -1,39 +1,39 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["list tweets migration", "list timeline migration", "v1.1 to v2 list tweets", "list tweets migration guide", "migrate list tweets"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing X API’s List Posts lookup endpoints - -The v2 List Posts lookup endpoint will replace the standard v1.1 [GET lists/statuses](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses). If you have code, apps, or tools that use this version of the endpoint, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you. - -The following tables compare the standard v1.1 and X API v2 List endpoints: - -**List Lookup by ID** - -| | | | -| :--- | :--- | :--- | -| Description | Standard v1.1 | X API v2 | -| HTTP methods supported | `GET` | `GET` | -| Host domain | `https://api.x.com` | `https://api.x.com` | -| Endpoint path | `/1.1/lists/statuses.json` | `/2/lists/:id/tweets` | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 900 requests per 15 min with OAuth 1.0a

900 requests per 15min with App only | 900 requests per 15 min with OAuth 1.0a

900 requests per 15 min with OAuth 2.0

900 requests per 15 min with App only | - -To access the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info). When authenticating, you must use keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  - -Learn more about getting access to the X API v2 endpoints in our [getting started](/x-api/getting-started/getting-access) page. -
- - - +--- +title: Overview +sidebarTitle: Overview +keywords: ["list tweets migration", "list timeline migration", "v1.1 to v2 list tweets", "list tweets migration guide", "migrate list tweets"] + + +import { Button } from '/snippets/button.mdx'; + +## Comparing X API’s List Posts lookup endpoints + +The v2 List Posts lookup endpoint will replace the standard v1.1 [GET lists/statuses](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses). If you have code, apps, or tools that use this version of the endpoint, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you. + +The following tables compare the standard v1.1 and X API v2 List endpoints: + +**List Lookup by ID** + +| | | | +| :--- | :--- | :--- | +| Description | Standard v1.1 | X API v2 | +| HTTP methods supported | `GET` | `GET` | +| Host domain | `https://api.x.com` | `https://api.x.com` | +| Endpoint path | `/1.1/lists/statuses.json` | `/2/lists/:id/tweets` | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 900 requests per 15 min with OAuth 1.0a

900 requests per 15min with App only | 900 requests per 15 min with OAuth 1.0a

900 requests per 15 min with OAuth 2.0

900 requests per 15 min with App only | + +To access the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info). When authenticating, you must use keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  + +Learn more about getting access to the X API v2 endpoints in our [getting started](/x-api/getting-started/getting-access) page. +
+ + +
\ No newline at end of file diff --git a/x-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx b/x-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx index ed4f31da2..77eb8e4ca 100644 --- a/x-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx @@ -1,174 +1,176 @@ ---- -title: v1 to v2 -sidebarTitle: v1 to v2 -keywords: ["v1.1 to v2 migration", "list tweets migration", "migrate list tweets", "standard to v2 list tweets", "v1 to v2 list tweets", "migration guide"] ---- - -import { Button } from '/snippets/button.mdx'; - -### List Posts lookup: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [GET lists/statuses](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses) endpoint, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 endpoints. - -* **Similarities** - * Authentication methods - * Rate limits -* **Differences** - * Endpoint URLs - * App and Project requirements - * Data objects per request limits - * Response data formats - * Request parameters - -#### Similarities - -**Authentication** - -Both endpoint versions support both [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-2-0). Therefore, if you were previously using one of the standard v1.1 List Posts lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see [this App only guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -**Rate limits** - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| /1.1/lists/statuses.json

900 requests per 15-minute window with OAuth 1.0a User Context

900 requests per 15-minute window with App only | /2/lists/:id/tweets

900 requests per 15-minute window with OAuth 1.0a User Context

900 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE

900 requests per 15-minute window with App only | - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * GET https://api.x.com/1.1/lists/statuses.json - (Lookup Tweets from a specified List) -* X API v2 endpoint: - * GET https://api.x.com/2/lists/:id/tweets - (Lookup Tweets from a specified List) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - -**Data objects per request limits** - -The standard v1.1 /lists/statuses endpoint allows you to return up to 5000 Posts per request. The new v2 endpoints allow you to return up to 100 Posts per request. By default, 100 user objects will be returned, to change the number of results you will need to pass a query parameter max_results= with a number between 1-100; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request. - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default and then have the option to use parameters to identify which additional fields or sets of fields should return in the payload. - -The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any Post fields that you request from this endpoint will return in the primary Post object. Any expanded object fields will return an includes object within your response. You can then match any expanded objects back to the primary Post object by matching the IDs from the primary object and in expanded objects. - -Here are examples of possible Post fields and expansions: - -* attachments -* author_id -* context_annotations -* created_at -* geo -* lang - - -| | | -| :--- | :--- | -| **Endpoint** | **Expansion** | -| /2/lists/:id/tweets | author_id | - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration) that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a **statuses** array, while X API v2 returns a **data** array. - -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as **contributors** and **user.translator_type** are being removed. - -* Instead of using both **favorites** (in Post object) and **favourites** (in user object), X API v2 uses the term **like**. - -* X is adopting the convention that JSON values with no value (for example, **null**) are not written to the payload. Post and user attributes are only included if they have non-null values. - - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| | | -| :--- | :--- | -| Standard v1.1 | X API v2 | -| list_id | id | -| slug | No equivalent | -| owner\_screen\_name | No equivalent | -| owner_id | Requested with expansions parameter with value of author_id | -| since_id | No equivalent | -| max_id | No equivalent | -| include_entities | Requested with tweet.fields parameter with value of entities | -| include_rts | No equivalent | -| count | max_results | - ---- - -## Code examples - -### Get Posts from a List (v2) - - - -```bash cURL -curl "https://api.x.com/2/lists/84839422/tweets?tweet.fields=created_at,public_metrics&max_results=100" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/lists/84839422/tweets" - -params = { - "tweet.fields": "created_at,public_metrics", - "max_results": 100 -} -headers = {"Authorization": f"Bearer {bearer_token}"} - -response = requests.get(url, headers=headers, params=params) -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get Posts from a List -for page in client.lists.get_tweets( - "84839422", - tweet_fields=["created_at", "public_metrics"], - max_results=100 -): - for post in page.data: - print(f"{post.created_at}: {post.text[:50]}...") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get Posts from a List -const paginator = client.lists.getTweets("84839422", { - tweetFields: ["created_at", "public_metrics"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`); - }); -} -``` - - +--- +title: v1 to v2 +sidebarTitle: v1 to v2 +keywords: ["v1.1 to v2 migration", "list tweets migration", "migrate list tweets", "standard to v2 list tweets", "v1 to v2 list tweets", "migration guide"] + + +--- + +import { Button } from '/snippets/button.mdx'; + +### List Posts lookup: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [GET lists/statuses](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses) endpoint, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 endpoints. + +* **Similarities** + * Authentication methods + * Rate limits +* **Differences** + * Endpoint URLs + * App and Project requirements + * Data objects per request limits + * Response data formats + * Request parameters + +#### Similarities + +**Authentication** + +Both endpoint versions support both [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-2-0). Therefore, if you were previously using one of the standard v1.1 List Posts lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see [this App only guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). + +**Rate limits** + +| | | +| :--- | :--- | +| **Standard v1.1** | **X API v2** | +| /1.1/lists/statuses.json

900 requests per 15-minute window with OAuth 1.0a User Context

900 requests per 15-minute window with App only | /2/lists/:id/tweets

900 requests per 15-minute window with OAuth 1.0a User Context

900 requests per 15-minute window with OAuth 2.0 Authorization Code with PKCE

900 requests per 15-minute window with App only | + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * GET https://api.x.com/1.1/lists/statuses.json + (Lookup Tweets from a specified List) +* X API v2 endpoint: + * GET https://api.x.com/2/lists/:id/tweets + (Lookup Tweets from a specified List) + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. + +**Data objects per request limits** + +The standard v1.1 /lists/statuses endpoint allows you to return up to 5000 Posts per request. The new v2 endpoints allow you to return up to 100 Posts per request. By default, 100 user objects will be returned, to change the number of results you will need to pass a query parameter max_results= with a number between 1-100; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request. + +**Response data format** + +One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. + +For the standard endpoints, you receive many of the response fields by default and then have the option to use parameters to identify which additional fields or sets of fields should return in the payload. + +The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any Post fields that you request from this endpoint will return in the primary Post object. Any expanded object fields will return an includes object within your response. You can then match any expanded objects back to the primary Post object by matching the IDs from the primary object and in expanded objects. + +Here are examples of possible Post fields and expansions: + +* attachments +* author_id +* context_annotations +* created_at +* geo +* lang + + +| | | +| :--- | :--- | +| **Endpoint** | **Expansion** | +| /2/lists/:id/tweets | author_id | + +We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). + +We have also put together a [data format migration guide](/x-api/migrate/data-format-migration) that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. + +In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. + +* At the JSON root level, the standard endpoints return Post objects in a **statuses** array, while X API v2 returns a **data** array. + +* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as **contributors** and **user.translator_type** are being removed. + +* Instead of using both **favorites** (in Post object) and **favourites** (in user object), X API v2 uses the term **like**. + +* X is adopting the convention that JSON values with no value (for example, **null**) are not written to the payload. Post and user attributes are only included if they have non-null values. + + +**Request parameters** + +The following standard v1.1 request parameters have equivalents in X API v2: + +| | | +| :--- | :--- | +| Standard v1.1 | X API v2 | +| list_id | id | +| slug | No equivalent | +| owner\_screen\_name | No equivalent | +| owner_id | Requested with expansions parameter with value of author_id | +| since_id | No equivalent | +| max_id | No equivalent | +| include_entities | Requested with tweet.fields parameter with value of entities | +| include_rts | No equivalent | +| count | max_results | + +--- + +## Code examples + +### Get Posts from a List (v2) + + + +```bash cURL +curl "https://api.x.com/2/lists/84839422/tweets?tweet.fields=created_at,public_metrics&max_results=100" \ + -H "Authorization: Bearer $BEARER_TOKEN" +``` + +```python Python +import requests + +bearer_token = "YOUR_BEARER_TOKEN" +url = "https://api.x.com/2/lists/84839422/tweets" + +params = { + "tweet.fields": "created_at,public_metrics", + "max_results": 100 +} +headers = {"Authorization": f"Bearer {bearer_token}"} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_BEARER_TOKEN") + +# Get Posts from a List +for page in client.lists.get_tweets( + "84839422", + tweet_fields=["created_at", "public_metrics"], + max_results=100 +): + for post in page.data: + print(f"{post.created_at}: {post.text[:50]}...") +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); + +// Get Posts from a List +const paginator = client.lists.getTweets("84839422", { + tweetFields: ["created_at", "public_metrics"], + maxResults: 100, +}); + +for await (const page of paginator) { + page.data?.forEach((post) => { + console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`); + }); +} +``` + + diff --git a/x-api/lists/manage-lists/integrate.mdx b/x-api/lists/manage-lists/integrate.mdx index afca11be2..dd024151f 100644 --- a/x-api/lists/manage-lists/integrate.mdx +++ b/x-api/lists/manage-lists/integrate.mdx @@ -1,168 +1,167 @@ ---- -title: Integration guide -sidebarTitle: Integration guide -keywords: ["manage lists integration", "list management integration", "lists integration guide", "list management setup"] ---- - -import { Button } from '/snippets/button.mdx'; - -This page covers tools and key concepts for integrating the Lists endpoints. - ---- - -## Helpful tools - -Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: - -#### Postman - -Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. - -#### Code samples - -Are you interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). - -#### Third-party libraries - -Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. - -### Key concepts - -#### Authentication - -All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. - -These specific endpoints requires the use of [OAuth 1.0a User Context](/resources/fundamentals/authentication), which means that you must use a set of API keys and user Access Tokens to make a successful request. The Access Tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize or authenticate your App using the [3-legged OAuth flow](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). - -Please note that OAuth 1.0a can be tricky to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries) or a tool like Postman to properly authenticate your requests. - - -#### Developer Console, Projects, and developer Apps - -To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. - - -#### Rate limits - -Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. - -These endpoints are rate limited at the user level, meaning that the authenticated user that you are making the request on behalf of can only call the endpoint a certain number of times across any developer App. - -The chart below shows the rate limits for each endpoint. - -| | | | -| :--- | :--- | :--- | -| **Endpoint** | **HTTP method** | **Rate limit** | -| /2/lists | POST | 300 requests per 15 minutes | -| /2/lists/:id | DELETE / PUT | 300 requests per 15 minutes | - ---- - -### Code examples - -#### Create a List - - - -```bash cURL -curl -X POST "https://api.x.com/2/lists" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"name": "My List", "description": "A list of interesting accounts"}' -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Create a new List -response = client.lists.create( - name="My List", - description="A list of interesting accounts" -) -print(response.data) -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Create a new List -const response = await client.lists.create({ - name: "My List", - description: "A list of interesting accounts", -}); -console.log(response.data); -``` - - - -#### Update a List - - - -```bash cURL -curl -X PUT "https://api.x.com/2/lists/123456789" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"name": "Updated List Name"}' -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Update a List -response = client.lists.update( - list_id="123456789", - name="Updated List Name" -) -print(response.data) -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Update a List -const response = await client.lists.update("123456789", { - name: "Updated List Name", -}); -console.log(response.data); -``` - - +--- +title: Integration guide +sidebarTitle: Integration guide +keywords: ["manage lists integration", "list management integration", "lists integration guide", "list management setup"] + + +--- + +import { Button } from '/snippets/button.mdx'; + +This page covers tools and key concepts for integrating the Lists endpoints. + +## Helpful tools + +Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: + +#### Postman + +Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. + +#### Code samples + +Are you interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). + +#### Third-party libraries + +Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. + +### Key concepts + +#### Authentication + +All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. + +These specific endpoints requires the use of [OAuth 1.0a User Context](/resources/fundamentals/authentication), which means that you must use a set of API keys and user Access Tokens to make a successful request. The Access Tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize or authenticate your App using the [3-legged OAuth flow](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). + +Please note that OAuth 1.0a can be tricky to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries) or a tool like Postman to properly authenticate your requests. + + +#### Developer Console, Projects, and developer Apps + +To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. + + +#### Rate limits + +Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. + +These endpoints are rate limited at the user level, meaning that the authenticated user that you are making the request on behalf of can only call the endpoint a certain number of times across any developer App. + +The chart below shows the rate limits for each endpoint. + +| | | | +| :--- | :--- | :--- | +| **Endpoint** | **HTTP method** | **Rate limit** | +| /2/lists | POST | 300 requests per 15 minutes | +| /2/lists/:id | DELETE / PUT | 300 requests per 15 minutes | + +--- + +### Code examples + +#### Create a List + + + +```bash cURL +curl -X POST "https://api.x.com/2/lists" \ + -H "Authorization: OAuth ..." \ + -H "Content-Type: application/json" \ + -d '{"name": "My List", "description": "A list of interesting accounts"}' +``` + +```python Python SDK +from xdk import Client +from xdk.oauth1_auth import OAuth1 + +oauth1 = OAuth1( + api_key="YOUR_API_KEY", + api_secret="YOUR_API_SECRET", + access_token="YOUR_ACCESS_TOKEN", + access_token_secret="YOUR_ACCESS_TOKEN_SECRET" +) + +client = Client(auth=oauth1) + +# Create a new List +response = client.lists.create( + name="My List", + description="A list of interesting accounts" +) +print(response.data) +``` + +```javascript JavaScript SDK +import { Client, OAuth1 } from "@xdevplatform/xdk"; + +const oauth1 = new OAuth1({ + apiKey: "YOUR_API_KEY", + apiSecret: "YOUR_API_SECRET", + accessToken: "YOUR_ACCESS_TOKEN", + accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", +}); + +const client = new Client({ oauth1 }); + +// Create a new List +const response = await client.lists.create({ + name: "My List", +}); +console.log(response.data); +``` + + + +#### Update a List + + + +```bash cURL +curl -X PUT "https://api.x.com/2/lists/123456789" \ + -H "Authorization: OAuth ..." \ + -H "Content-Type: application/json" \ + -d '{"name": "Updated List Name"}' +``` + +```python Python SDK +from xdk import Client +from xdk.oauth1_auth import OAuth1 + +oauth1 = OAuth1( + api_key="YOUR_API_KEY", + api_secret="YOUR_API_SECRET", + access_token="YOUR_ACCESS_TOKEN", + access_token_secret="YOUR_ACCESS_TOKEN_SECRET" +) + +client = Client(auth=oauth1) + +# Update a List +response = client.lists.update( + list_id="123456789", + name="Updated List Name" +) +print(response.data) +``` + +```javascript JavaScript SDK +import { Client, OAuth1 } from "@xdevplatform/xdk"; + +const oauth1 = new OAuth1({ + apiKey: "YOUR_API_KEY", + apiSecret: "YOUR_API_SECRET", + accessToken: "YOUR_ACCESS_TOKEN", + accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", +}); + +const client = new Client({ oauth1 }); + +// Update a List +const response = await client.lists.update("123456789", { + name: "Updated List Name", +}); +console.log(response.data); +``` + + diff --git a/x-api/lists/manage-lists/migrate/overview.mdx b/x-api/lists/manage-lists/migrate/overview.mdx index d3506e023..5b241952b 100644 --- a/x-api/lists/manage-lists/migrate/overview.mdx +++ b/x-api/lists/manage-lists/migrate/overview.mdx @@ -1,58 +1,58 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["lists migration", "manage lists migration", "v1.1 to v2 lists", "lists migration guide", "migrate lists"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing X API’s Lists endpoints - -The v2 manage Lists endpoints will eventually replace [POST lists/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-create), [POST lists/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy), and [POST lists/update](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-update). If you have code, apps, or tools that use an older version of these endpoints and are considering migrating to the newer X API v2, then this guide is for you.  - -The following tables compare the standard v1.1 and X API v2 List endpoints: - -**Create a List** - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | POST | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/lists/create.json | /2/lists | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | - -**Delete a List** - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | DELETE | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/lists/destroy.json | /2/lists/:id | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | - -**Update a List** - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | PUT | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/lists/update.json | /2/lists/:id | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | - -To access the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info). When authenticating, you must use keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  - -Learn more about getting access to the X API v2 endpoints in our [getting started](/x-api/getting-started/getting-access) page. -
- - - +--- +title: Overview +sidebarTitle: Overview +keywords: ["lists migration", "manage lists migration", "v1.1 to v2 lists", "lists migration guide", "migrate lists"] + + +import { Button } from '/snippets/button.mdx'; + +## Comparing X API’s Lists endpoints + +The v2 manage Lists endpoints will eventually replace [POST lists/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-create), [POST lists/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy), and [POST lists/update](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-update). If you have code, apps, or tools that use an older version of these endpoints and are considering migrating to the newer X API v2, then this guide is for you.  + +The following tables compare the standard v1.1 and X API v2 List endpoints: + +**Create a List** + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | POST | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/lists/create.json | /2/lists | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | + +**Delete a List** + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | DELETE | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/lists/destroy.json | /2/lists/:id | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | + +**Update a List** + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | PUT | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/lists/update.json | /2/lists/:id | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 300 requests per 15 min (per user) | + +To access the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info). When authenticating, you must use keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  + +Learn more about getting access to the X API v2 endpoints in our [getting started](/x-api/getting-started/getting-access) page. +
+ + +
\ No newline at end of file diff --git a/x-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.mdx b/x-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.mdx index 68b460f36..11a3b2479 100644 --- a/x-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.mdx @@ -1,219 +1,54 @@ ---- -title: v1 to v2 -sidebarTitle: v1 to v2 -keywords: ["v1.1 to v2 migration", "lists migration", "migrate lists", "standard to v2 lists", "v1 to v2 lists", "migration guide"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Manage Lists: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST lists/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-create), [POST lists/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy), and [POST lists/update](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-update) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage List endpoints. - -* **Similarities** - * Authentication -* **Differences** - * Endpoint URLs - * App and Project requirements - * HTTP methods - * Rate limits - * Request parameters - -#### Similarities - -**Authentication** - -Both endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage Lists endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/lists/create.json - (Creates a List) - * POST https://api.x.com/1.1/lists/destroy.json - (Deletes a List) - * POST https://api.x.com/1.1/lists/update.json - (Updates a List) -* X API v2 endpoint: - * POST https://api.x.com/2/lists - (Creates a List) - - * DELETE https://api.x.com/2/lists/:id - (Deletes a List) - - * PUT https://api.x.com/2/lists/:id - (Updates a List) - - - -**Rate limits** - -| **Standard v1.1** | **X API v2** | -| :--- | :--- | -| /1.1/lists/create.json

none | /2/lists

300 requests per 15-minute window with OAuth 1.0a User Context | -| /1.1/lists/destroy.json

none | /2/lists/:id

300 requests per 15-minute window with OAuth 1.0a User Context | -| /1.1/lists/update.json

none | /2/lists/:id

300 requests per 15-minute window with OAuth 1.0a User Context | - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps related to a project. - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -**Create a List** - -| **Standard** | **X API v2** | -| :--- | :--- | -| name | name | -| mode | private | -| description | description | - -**Delete/Update a List** - -| **Standard** | **X API v2** | -| :--- | :--- | -| owner\_screen\_name | No equivalent | -| owner_id | No equivalent | -| list_id | id | -| slug | No equivalent | - - -**Please note:** Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters (for the POST endpoint) or path parameters (for the DELETE and PUT endpoints). - - ---- - -## Code examples - -### Create a List (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/lists" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"name": "My List", "description": "A great list"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/lists" -data = {"name": "My List", "description": "A great list"} - -response = requests.post(url, auth=auth, json=data) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Create a List -response = client.lists.create(name="My List", description="A great list") -print(f"Created List: {response.data.id}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Create a List -const response = await client.lists.create({ - name: "My List", - description: "A great list", -}); -console.log(`Created List: ${response.data?.id}`); -``` - - - -### Delete a List (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/lists/123456789" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/lists/123456789" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Delete a List -response = client.lists.delete("123456789") -print(f"Deleted: {response.data.deleted}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Delete a List -const response = await client.lists.delete("123456789"); -console.log(`Deleted: ${response.data?.deleted}`); -``` - - +--- +title: v1 to v2 +sidebarTitle: v1 to v2 +keywords: ["v1.1 to v2 migration", "lists migration", "migrate lists", "standard to v2 lists", "v1 to v2 lists", "migration guide"] + + +--- +import { Button } from '/snippets/button.mdx'; + +### Manage Lists: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST lists/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-create), [POST lists/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy), and [POST lists/update](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-update) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage List endpoints. + +* **Similarities** + * Authentication +* **Differences** + * Endpoint URLs + * App and Project requirements + * HTTP methods + * Rate limits + * Request parameters + +#### Similarities + +**Authentication** + +Both endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage Lists endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/lists/create.json + (Creates a List) + * POST https://api.x.com/1.1/lists/destroy.json + (Deletes a List) + * POST https://api.x.com/1.1/lists/update.json + (Updates a List) +* X API v2 endpoint: + * POST https://api.x.com/2/lists + (Creates a List) + + * DELETE https://api.x.com/2/lists/:id + (Deletes a List) + + * PUT https://api.x.com/2/lists/:id + (Updates a List) + + + +**Rate limits** + +| **Standard v1 \ No newline at end of file diff --git a/x-api/lists/pinned-lists/integrate.mdx b/x-api/lists/pinned-lists/integrate.mdx index 415e104ce..999689256 100644 --- a/x-api/lists/pinned-lists/integrate.mdx +++ b/x-api/lists/pinned-lists/integrate.mdx @@ -1,73 +1,73 @@ ---- -title: Integration guide -sidebarTitle: Integration guide -keywords: ["pinned lists integration", "pin lists integration", "pinned lists guide", "pinned lists setup", "list pinning integration"] ---- - -import { Button } from '/snippets/button.mdx'; - -This page covers tools and key concepts for integrating the pinned Lists endpoints. - ---- - -## Helpful tools - -Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: - -### Postman - -Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. - -### Code samples - -Interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). - -### Third-party libraries - -Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. - ---- - -## Key concepts - -### Authentication - -All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use OAuth 1.0a User Context to authenticate your requests to this endpoint. - -[OAuth 1.0a User Context](/resources/fundamentals/authentication), which means that you must use a set of API Keys and user Access Tokens to make a successful request. The access tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the [3-legged OAuth flow](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens). - -Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries), use a tool like Postman. - -### Developer Console, Projects, and developer Apps - -To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. - -### Rate limits - -Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests you can make on behalf of your app or on behalf of an authenticated user. - -These endpoints are rate limited at the user level, meaning that the authenticated user that you are making the request on behalf of can only call the endpoint a certain number of times across any developer App. - -The chart below shows the rate limits for each endpoint. - -| Endpoint | HTTP method | Rate limit | -| :--- | :--- | :--- | -| /2/users/:id/pinned_lists | POST | 50 requests per 15 minutes | -| /2/users/:id/pinned_lists/:list_id | DELETE | 50 requests per 15 minutes | -| /2/users/:id/pinned_lists | GET | 15 requests per 15 minutes | - -### Fields and expansions - -The X API v2 GET endpoint allows users to select exactly which data they want to return from the API using a set of tools called `fields` and `expansions`. The `expansions` parameter allows you to expand objects referenced in the payload. For example, looking up pinned Lists allows you to pull the following [expansions](/x-api/fundamentals/expansions): - -* `owner_id` - -The `fields` parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. This endpoint delivers user objects primarily. By default, the List object returns the `id`, and `name` fields. To receive additional fields such as `list.created_at` or `list.description`, you will have to specifically request those using a fields parameter. - -We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). - -The chart below shows the field and expansions available for the lookup endpoint: - -| Endpoint | Fields | Expansions | -| :--- | :--- | :--- | -| /2/users/:id/pinned_lists | `list.fields`, `user.fields` | `owner_id` | +--- +title: Integration guide +sidebarTitle: Integration guide +keywords: ["pinned lists integration", "pin lists integration", "pinned lists guide", "pinned lists setup", "list pinning integration"] + + +--- + +import { Button } from '/snippets/button.mdx'; + +This page covers tools and key concepts for integrating the pinned Lists endpoints. + +## Helpful tools + +Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: + +### Postman + +Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. + +### Code samples + +Interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). + +### Third-party libraries + +Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. + +--- + +## Key concepts + +### Authentication + +All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use OAuth 1.0a User Context to authenticate your requests to this endpoint. + +[OAuth 1.0a User Context](/resources/fundamentals/authentication), which means that you must use a set of API Keys and user Access Tokens to make a successful request. The access tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the [3-legged OAuth flow](https://developer.x.com/resources/fundamentals/authentication/obtaining-user-access-tokens). + +Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries), use a tool like Postman. + +### Developer Console, Projects, and developer Apps + +To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. + +### Rate limits + +Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests you can make on behalf of your app or on behalf of an authenticated user. + +These endpoints are rate limited at the user level, meaning that the authenticated user that you are making the request on behalf of can only call the endpoint a certain number of times across any developer App. + +The chart below shows the rate limits for each endpoint. + +| Endpoint | HTTP method | Rate limit | +| :--- | :--- | :--- | +| /2/users/:id/pinned_lists | POST | 50 requests per 15 minutes | +| /2/users/:id/pinned_lists/:list_id | DELETE | 50 requests per 15 minutes | +| /2/users/:id/pinned_lists | GET | 15 requests per 15 minutes | + +### Fields and expansions + +The X API v2 GET endpoint allows users to select exactly which data they want to return from the API using a set of tools called `fields` and `expansions`. The `expansions` parameter allows you to expand objects referenced in the payload. For example, looking up pinned Lists allows you to pull the following [expansions](/x-api/fundamentals/expansions): + +* `owner_id` + +The `fields` parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. This endpoint delivers user objects primarily. By default, the List object returns the `id`, and `name` fields. To receive additional fields such as `list.created_at` or `list.description`, you will have to specifically request those using a fields parameter. + +We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). + +The chart below shows the field and expansions available for the lookup endpoint: + +| Endpoint | Fields | Expansions | +| :--- | :--- | :--- | +| /2/users/:id/pinned_lists | `list.fields`, `user.fields` | `owner_id` | diff --git a/x-api/lists/remove-list-member.mdx b/x-api/lists/remove-list-member.mdx index 6fb011242..e7f273924 100644 --- a/x-api/lists/remove-list-member.mdx +++ b/x-api/lists/remove-list-member.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/lists/{id}/members/{user_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/lists/update-list.mdx b/x-api/lists/update-list.mdx index bdb7eb20f..139a3a6e3 100644 --- a/x-api/lists/update-list.mdx +++ b/x-api/lists/update-list.mdx @@ -1,3 +1,4 @@ --- openapi: put /2/lists/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/llms.txt b/x-api/llms.txt new file mode 100644 index 000000000..3073ba585 --- /dev/null +++ b/x-api/llms.txt @@ -0,0 +1,434 @@ +# X API v2 + +> Complete reference for the modern X API v2 including Posts, Users, DMs, Lists, Spaces, Media, real-time Streams, Compliance, Webhooks, and more. + +## Core +- [X API](https://docs.x.com/x-api/introduction.md): Programmatic access to X's posts, users, spaces, and more +- [X API Overview](https://docs.x.com/x-api/overview.md): Complete API reference for posts, users, spaces, DMs, lists, trends, and more + +## Account Activity +- [Create Replay Job](https://docs.x.com/x-api/account-activity/create-replay-job.md): Reference documentation for the endpoint and related functionality. +- [Create Subscription](https://docs.x.com/x-api/account-activity/create-subscription.md): Reference documentation for the endpoint and related functionality. +- [Delete Subscription](https://docs.x.com/x-api/account-activity/delete-subscription.md): Reference documentation for the endpoint and related functionality. +- [Get Subscription Count](https://docs.x.com/x-api/account-activity/get-subscription-count.md): Reference documentation for the endpoint and related functionality. +- [Get Subscriptions](https://docs.x.com/x-api/account-activity/get-subscriptions.md): Reference documentation for the endpoint and related functionality. +- [V2 Account Activity API](https://docs.x.com/x-api/account-activity/introduction.md): Receive real-time account activity events via webhooks +- [Quickstart](https://docs.x.com/x-api/account-activity/quickstart.md): Set up Account Activity API subscriptions and start receiving real-time events +- [Validate Subscription](https://docs.x.com/x-api/account-activity/validate-subscription.md): Reference documentation for the endpoint and related functionality. +- [v2 Account Activity API Migration Guide](https://docs.x.com/x-api/account-activity/migrate/overview.md): This guide helps you migrate from the legacy Enterprise Account Activity API to the V2 Account Activity API. The core + +## Activity +- [Activity Stream](https://docs.x.com/x-api/activity/activity-stream.md): Reference documentation for the endpoint and related functionality. +- [Create X Activity Subscription](https://docs.x.com/x-api/activity/create-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. +- [Delete X Activity Subscriptions By Ids](https://docs.x.com/x-api/activity/delete-x-activity-subscriptions-by-ids.md): Reference documentation for the endpoint and related functionality. +- [Deletes X Activity Subscription](https://docs.x.com/x-api/activity/deletes-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. +- [Get X Activity Subscriptions](https://docs.x.com/x-api/activity/get-x-activity-subscriptions.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/x-api/activity/introduction.md): import { Button } from '/snippets/button.mdx'; The X Activity API (XAA) endpoint group allows developers to tap in to +- [Quickstart](https://docs.x.com/x-api/activity/quickstart.md): This guide explains how to subscribe for and receive events using the X Activity API endpoints. There generally 3 step +- [Update X Activity Subscription](https://docs.x.com/x-api/activity/update-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. + +## Bookmarks +- [Create Bookmark](https://docs.x.com/x-api/bookmarks/create-bookmark.md): Reference documentation for the endpoint and related functionality. +- [Delete Bookmark](https://docs.x.com/x-api/bookmarks/delete-bookmark.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmark Folders](https://docs.x.com/x-api/bookmarks/get-bookmark-folders.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmarks By Folder Id](https://docs.x.com/x-api/bookmarks/get-bookmarks-by-folder-id.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmarks](https://docs.x.com/x-api/bookmarks/get-bookmarks.md): Reference documentation for the endpoint and related functionality. + +## Chat +- [Add Members To A Chat Group Conversation](https://docs.x.com/x-api/chat/add-members-to-a-chat-group-conversation.md): Reference documentation for the endpoint and related functionality. +- [Add Public Key](https://docs.x.com/x-api/chat/add-public-key.md): Reference documentation for the endpoint and related functionality. +- [Append Chat Media Upload](https://docs.x.com/x-api/chat/append-chat-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Create Chat Group Conversation](https://docs.x.com/x-api/chat/create-chat-group-conversation.md): Reference documentation for the endpoint and related functionality. +- [Download Chat Media](https://docs.x.com/x-api/chat/download-chat-media.md): Reference documentation for the endpoint and related functionality. +- [Finalize Chat Media Upload](https://docs.x.com/x-api/chat/finalize-chat-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Get Chat Conversation](https://docs.x.com/x-api/chat/get-chat-conversation.md): Reference documentation for the endpoint and related functionality. +- [Get Chat Conversations](https://docs.x.com/x-api/chat/get-chat-conversations.md): Reference documentation for the endpoint and related functionality. +- [Get User Public Keys](https://docs.x.com/x-api/chat/get-user-public-keys.md): Reference documentation for the endpoint and related functionality. +- [Initialize Chat Group](https://docs.x.com/x-api/chat/initialize-chat-group.md): Reference documentation for the endpoint and related functionality. +- [Initialize Chat Media Upload](https://docs.x.com/x-api/chat/initialize-chat-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Initialize Conversation Keys](https://docs.x.com/x-api/chat/initialize-conversation-keys.md): Reference documentation for the endpoint and related functionality. +- [Mark Conversation As Read](https://docs.x.com/x-api/chat/mark-conversation-as-read.md): Reference documentation for the endpoint and related functionality. +- [Send Chat Message](https://docs.x.com/x-api/chat/send-chat-message.md): Reference documentation for the endpoint and related functionality. +- [Send Typing Indicator](https://docs.x.com/x-api/chat/send-typing-indicator.md): Reference documentation for the endpoint and related functionality. + +## Communities +- [Get Community By Id](https://docs.x.com/x-api/communities/get-community-by-id.md): Reference documentation for the endpoint and related functionality. +- [Search Communities](https://docs.x.com/x-api/communities/search-communities.md): Reference documentation for the endpoint and related functionality. +- [Communities Lookup](https://docs.x.com/x-api/communities/lookup/introduction.md): Retrieve Community details by ID +- [Communities Search](https://docs.x.com/x-api/communities/search/introduction.md): Search for Communities by keyword + +## Community Notes +- [Create A Community Note](https://docs.x.com/x-api/community-notes/create-a-community-note.md): Reference documentation for the endpoint and related functionality. +- [Delete A Community Note](https://docs.x.com/x-api/community-notes/delete-a-community-note.md): Reference documentation for the endpoint and related functionality. +- [Evaluate A Community Note](https://docs.x.com/x-api/community-notes/evaluate-a-community-note.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/x-api/community-notes/introduction.md): The Community Notes Endpoints in the X API v2 allow developers to search for and propose Community Notes on X programm +- [Quickstart](https://docs.x.com/x-api/community-notes/quickstart.md): Create and search Community Notes via the API +- [Search For Community Notes Written](https://docs.x.com/x-api/community-notes/search-for-community-notes-written.md): Reference documentation for the endpoint and related functionality. +- [Search For Posts Eligible For Community Notes](https://docs.x.com/x-api/community-notes/search-for-posts-eligible-for-community-notes.md): Reference documentation for the endpoint and related functionality. + +## Compliance +- [Create Compliance Job](https://docs.x.com/x-api/compliance/create-compliance-job.md): Reference documentation for the endpoint and related functionality. +- [Get Compliance Job By Id](https://docs.x.com/x-api/compliance/get-compliance-job-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Compliance Jobs](https://docs.x.com/x-api/compliance/get-compliance-jobs.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/x-api/compliance/streams/introduction.md): X is committed to our community of developers who build with the X API. As part of this commitment, we aim to make our +- [Integration guide](https://docs.x.com/x-api/compliance/batch-compliance/integrate.md): When using the Batch compliance endpoints, developers can batch upload large amounts of X data and understand what act +- [Batch Compliance](https://docs.x.com/x-api/compliance/batch-compliance/introduction.md): Check compliance status for Posts and users in bulk +- [Quickstart](https://docs.x.com/x-api/compliance/batch-compliance/quickstart.md): Create and run a batch compliance job + +## Connections +- [Get Connection History](https://docs.x.com/x-api/connections/get-connection-history.md): Reference documentation for the endpoint and related functionality. +- [Stream Connections](https://docs.x.com/x-api/connections/introduction.md): View and manage your streaming connections for X API v2 +- [Terminate All Connections](https://docs.x.com/x-api/connections/terminate-all-connections.md): Reference documentation for the endpoint and related functionality. +- [Terminate Connections By Endpoint](https://docs.x.com/x-api/connections/terminate-connections-by-endpoint.md): Reference documentation for the endpoint and related functionality. +- [Terminate Multiple Connections](https://docs.x.com/x-api/connections/terminate-multiple-connections.md): Reference documentation for the endpoint and related functionality. + +## Direct Messages +- [Create Dm Conversation](https://docs.x.com/x-api/direct-messages/create-dm-conversation.md): Reference documentation for the endpoint and related functionality. +- [Create Dm Message By Conversation Id](https://docs.x.com/x-api/direct-messages/create-dm-message-by-conversation-id.md): Reference documentation for the endpoint and related functionality. +- [Create Dm Message By Participant Id](https://docs.x.com/x-api/direct-messages/create-dm-message-by-participant-id.md): Reference documentation for the endpoint and related functionality. +- [Delete Dm Event](https://docs.x.com/x-api/direct-messages/delete-dm-event.md): Reference documentation for the endpoint and related functionality. +- [Download Dm Media](https://docs.x.com/x-api/direct-messages/download-dm-media.md): Reference documentation for the endpoint and related functionality. +- [Get Dm Event By Id](https://docs.x.com/x-api/direct-messages/get-dm-event-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Dm Events For A Dm Conversation 1](https://docs.x.com/x-api/direct-messages/get-dm-events-for-a-dm-conversation-1.md): Reference documentation for the endpoint and related functionality. +- [Get Dm Events For A Dm Conversation](https://docs.x.com/x-api/direct-messages/get-dm-events-for-a-dm-conversation.md): Reference documentation for the endpoint and related functionality. +- [Get Dm Events](https://docs.x.com/x-api/direct-messages/get-dm-events.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/x-api/direct-messages/blocks/introduction.md): The manage DM blocks endpoints enable you to block or unblock a specified account on behalf of an authenticated user. +- [Integration Guide](https://docs.x.com/x-api/direct-messages/lookup/integrate.md): Key concepts and best practices for integrating DM lookup endpoints +- [Direct Messages Lookup](https://docs.x.com/x-api/direct-messages/lookup/introduction.md): Retrieve Direct Message events and conversations +- [Migration guide](https://docs.x.com/x-api/direct-messages/lookup/migrate.md): 1 and v2 versions of the Direct Messages endpoints provide methods for looking up Direct Message events. +- [Quickstart](https://docs.x.com/x-api/direct-messages/lookup/quickstart.md): Retrieve Direct Message events and conversations +- [Integration Guide](https://docs.x.com/x-api/direct-messages/manage/integrate.md): Key concepts and best practices for sending Direct Messages +- [Manage Direct Messages](https://docs.x.com/x-api/direct-messages/manage/introduction.md): Send and delete Direct Messages +- [Migration guide](https://docs.x.com/x-api/direct-messages/manage/migrate.md): 1 and v2 versions of the Direct Messages endpoints provide methods for creating Direct Message messages. +- [Quickstart](https://docs.x.com/x-api/direct-messages/manage/quickstart.md): Send Direct Messages and create group conversations + +## Enterprise Gnip 2.0 +- [Enterprise](https://docs.x.com/x-api/enterprise-gnip-2.0/enterprise-gnip.md): Our enterprise APIs offer the highest level of access and reliability to those who depend on X data. Perfect as you sc +- [PowerTrack API](https://docs.x.com/x-api/enterprise-gnip-2.0/powertrack-api.md): This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the [ +- [Account Activity API: Enterprise](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/account-activity.md): Overview `Enterprise` The Account Activity API provides you the ability to subscribe to realtime activities related to +- [Data dictionary: Enterprise](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary.md): Interested in learning more about how the enterprise data formats map to the X API v2 format? +- [Data enrichments: Enterprise](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/data-enrichments.md): `Enterprise` Enterprise enrichments are additive metadata included in the response payload of some of the data APIs. T +- [Decahose API](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/decahose-api.md): [Enterprise](https://developer. +- [Edit Tweets](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets.md): Enterprise endpoints have been updated to provide edited Post metadata. The _Edit Posts _feature was first introduced +- [Engagement API](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/engagement-api.md): [`Enterprise`](https://developer. +- [Compliance Firehose API](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/firehouse.md): >**Please note** > >We have released a new compliance tool to X API v2 called [batch compliance](/x-api/compliance/bat +- [Gnip console](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/overview.md): >The enterprise console (at console. +- [Rate limits: Enterprise](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/rate-limits.md): Every day many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, +- [Rules and filtering: Enterprise](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering.md): Products utilizing enterprise operators deliver social data to you based on filtering rules you set up. Rules are made +- [Search API: Enterprise](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/search-api.md): >**Please note:** > >We have released a new version of [search Posts](/x-api/posts/search/introduction) and [Post coun +- [Usage API](https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/usage.md): The Usage API is a free REST API that provides programmatic access and visibility into activity consumption across pro + +## Fundamentals +- [API Consistency](https://docs.x.com/x-api/fundamentals/consistency.md): Consistent patterns across X API v2 endpoints +- [Consuming streaming data](https://docs.x.com/x-api/fundamentals/consuming-streaming-data.md): Best practices for building clients that consume X streaming APIs +- [Conversation ID](https://docs.x.com/x-api/fundamentals/conversation-id.md): Track and reconstruct conversation threads +- [Data Dictionary](https://docs.x.com/x-api/fundamentals/data-dictionary.md): Complete field reference for X API v2 objects +- [Edit Posts](https://docs.x.com/x-api/fundamentals/edit-posts.md): Working with edited posts in the X API +- [Expansions](https://docs.x.com/x-api/fundamentals/expansions.md): Include related objects in API responses +- [Fields](https://docs.x.com/x-api/fundamentals/fields.md): Request specific data fields in API responses +- [Handling disconnections](https://docs.x.com/x-api/fundamentals/handling-disconnections.md): Best practices for detecting and recovering from streaming disconnections +- [Handling high-volume capacity](https://docs.x.com/x-api/fundamentals/high-volume-capacity.md): Best practices for handling high-volume streaming data events +- [Metrics](https://docs.x.com/x-api/fundamentals/metrics.md): Access engagement metrics for posts and media +- [Pagination](https://docs.x.com/x-api/fundamentals/pagination.md): Navigate through large result sets +- [Post Annotations](https://docs.x.com/x-api/fundamentals/post-annotations.md): Entity and context annotations for semantic analysis +- [Usage and Billing](https://docs.x.com/x-api/fundamentals/post-cap.md): Understanding API usage tracking and pay-per-usage billing +- [X API Rate Limits](https://docs.x.com/x-api/fundamentals/rate-limits.md): Per-endpoint rate limits for X API v2 +- [Recovery and redundancy](https://docs.x.com/x-api/fundamentals/recovery-and-redundancy.md): Features for recovering missed data and building resilient streaming applications +- [Response Codes & Errors](https://docs.x.com/x-api/fundamentals/response-codes-and-errors.md): HTTP status codes and error handling for the X API +- [Versioning](https://docs.x.com/x-api/fundamentals/versioning.md): X API versioning strategy and deprecation policy + +## General +- [Get Openapi Spec](https://docs.x.com/x-api/general/get-openapi-spec.md): Reference documentation for the endpoint and related functionality. + +## Getting Started +- [About the X API](https://docs.x.com/x-api/getting-started/about-x-api.md): Overview of X API capabilities, versions, and resources +- [Getting Access](https://docs.x.com/x-api/getting-started/getting-access.md): Sign up for API access and get your credentials +- [Pricing](https://docs.x.com/x-api/getting-started/pricing.md): Pay-per-usage pricing for the X API + +## Lists +- [Add List Member](https://docs.x.com/x-api/lists/add-list-member.md): Reference documentation for the endpoint and related functionality. +- [Create List](https://docs.x.com/x-api/lists/create-list.md): Reference documentation for the endpoint and related functionality. +- [Delete List](https://docs.x.com/x-api/lists/delete-list.md): Reference documentation for the endpoint and related functionality. +- [Get List By Id](https://docs.x.com/x-api/lists/get-list-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get List Followers](https://docs.x.com/x-api/lists/get-list-followers.md): Reference documentation for the endpoint and related functionality. +- [Get List Members](https://docs.x.com/x-api/lists/get-list-members.md): Reference documentation for the endpoint and related functionality. +- [Get List Posts](https://docs.x.com/x-api/lists/get-list-posts.md): Reference documentation for the endpoint and related functionality. +- [Remove List Member](https://docs.x.com/x-api/lists/remove-list-member.md): Reference documentation for the endpoint and related functionality. +- [Update List](https://docs.x.com/x-api/lists/update-list.md): Reference documentation for the endpoint and related functionality. +- [Integration guide](https://docs.x.com/x-api/lists/list-tweets/integrate.md): This page covers tools and key concepts for integrating the List Posts lookup endpoint. +- [List Posts](https://docs.x.com/x-api/lists/list-tweets/introduction.md): Retrieve Posts from a List's timeline +- [Quickstart](https://docs.x.com/x-api/lists/list-tweets/quickstart.md): Get Posts from a List timeline +- [Overview](https://docs.x.com/x-api/lists/list-tweets/migrate/overview.md): The v2 List Posts lookup endpoint will replace the standard v1. 1 [GET lists/statuses](https://developer. +- [v1 to v2](https://docs.x.com/x-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET lists/statuses](https://developer. +- [Integration guide](https://docs.x.com/x-api/lists/list-members/integrate.md): This page covers tools and key concepts for integrating the List members endpoints. +- [List Members](https://docs.x.com/x-api/lists/list-members/introduction.md): View, add, and remove members from Lists +- [List Members Lookup](https://docs.x.com/x-api/lists/list-members/quickstart/list-members-lookup.md): Get members of a List +- [Manage List Members](https://docs.x.com/x-api/lists/list-members/quickstart/manage-list-members.md): Add and remove members from a List +- [List Members Overview](https://docs.x.com/x-api/lists/list-members/quickstart/overview.md): Get started with List members endpoints +- [List members lookup](https://docs.x.com/x-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET lists/members](https://developer. +- [Manage list members](https://docs.x.com/x-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST lists/members/create](https://developer. +- [Overview](https://docs.x.com/x-api/lists/list-members/migrate/overview.md): The v2 List members endpoint group will replace the standard v1. 1 [GET lists/members](https://developer. +- [Integration guide](https://docs.x.com/x-api/lists/pinned-lists/integrate.md): This page covers tools and key concepts for integrating the pinned Lists endpoints. +- [Pinned Lists](https://docs.x.com/x-api/lists/pinned-lists/introduction.md): View and manage pinned Lists +- [Manage Pinned Lists](https://docs.x.com/x-api/lists/pinned-lists/quickstart/manage-pinned-lists.md): Pin and unpin Lists +- [Pinned Lists Overview](https://docs.x.com/x-api/lists/pinned-lists/quickstart/overview.md): Get started with pinned List endpoints +- [Pinned Lists Lookup](https://docs.x.com/x-api/lists/pinned-lists/quickstart/pinned-list-lookup.md): Get a user's pinned Lists +- [Integration guide](https://docs.x.com/x-api/lists/manage-lists/integrate.md): This page covers tools and key concepts for integrating the Lists endpoints. +- [Manage Lists](https://docs.x.com/x-api/lists/manage-lists/introduction.md): Create, update, and delete Lists +- [Quickstart](https://docs.x.com/x-api/lists/manage-lists/quickstart.md): Create, update, and delete Lists +- [Overview](https://docs.x.com/x-api/lists/manage-lists/migrate/overview.md): The v2 manage Lists endpoints will eventually replace [POST lists/create](https://developer. +- [v1 to v2](https://docs.x.com/x-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST lists/create](https://developer. +- [Integration Guide](https://docs.x.com/x-api/lists/list-lookup/integrate.md): Key concepts and best practices for integrating List lookup +- [List Lookup](https://docs.x.com/x-api/lists/list-lookup/introduction.md): Retrieve List details by ID or get Lists owned by a user +- [Quickstart](https://docs.x.com/x-api/lists/list-lookup/quickstart.md): Look up Lists by ID or owner +- [Overview](https://docs.x.com/x-api/lists/list-lookup/migrate/overview.md): The v2 List lookup endpoint group will replace the standard v1. 1 [GET lists/show](https://developer. +- [v1 to v2](https://docs.x.com/x-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET lists/show](https://developer. + +## Marketplace +- [Get Marketplace Handle Availability](https://docs.x.com/x-api/marketplace/get-marketplace-handle-availability.md): Reference documentation for the endpoint and related functionality. + +## Media +- [Append Media Upload](https://docs.x.com/x-api/media/append-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Create Media Metadata](https://docs.x.com/x-api/media/create-media-metadata.md): Reference documentation for the endpoint and related functionality. +- [Create Media Subtitles](https://docs.x.com/x-api/media/create-media-subtitles.md): Reference documentation for the endpoint and related functionality. +- [Delete Media Subtitles](https://docs.x.com/x-api/media/delete-media-subtitles.md): Reference documentation for the endpoint and related functionality. +- [Finalize Media Upload](https://docs.x.com/x-api/media/finalize-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Get Media Analytics](https://docs.x.com/x-api/media/get-media-analytics.md): Reference documentation for the endpoint and related functionality. +- [Get Media By Media Key](https://docs.x.com/x-api/media/get-media-by-media-key.md): Reference documentation for the endpoint and related functionality. +- [Get Media By Media Keys](https://docs.x.com/x-api/media/get-media-by-media-keys.md): Reference documentation for the endpoint and related functionality. +- [Get Media Upload Status](https://docs.x.com/x-api/media/get-media-upload-status.md): Reference documentation for the endpoint and related functionality. +- [Initialize Media Upload](https://docs.x.com/x-api/media/initialize-media-upload.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/x-api/media/introduction.md): A media object represents a single photo, video or animated GIF. Media objects are used by many endpoints within the X +- [Upload Media](https://docs.x.com/x-api/media/upload-media.md): Reference documentation for the endpoint and related functionality. +- [Best practices](https://docs.x.com/x-api/media/quickstart/best-practices.md): There are a few important concepts to understand when using the [`POST /2/media/upload`](/x-api/media/media-upload) en +- [Chunked Media Upload](https://docs.x.com/x-api/media/quickstart/media-upload-chunked.md): Upload videos and large media files using chunked upload + +## Migrate +- [Data Formation Migration](https://docs.x.com/x-api/migrate/data-format-migration.md): With the launch of the v2 version of the X API, we have adopted a new data response format and method of requesting di +- [Overview](https://docs.x.com/x-api/migrate/overview.md): import { Button } from +- [Ready To Migrate](https://docs.x.com/x-api/migrate/ready-to-migrate.md) +- [X API endpoint map](https://docs.x.com/x-api/migrate/x-api-endpoint-map.md): The following table maps the X API v2 endpoints to the corresponding standard v1. 1, and enterprise endpoints. + +## News +- [Get News Stories By Id](https://docs.x.com/x-api/news/get-news-stories-by-id.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/x-api/news/introduction.md): The news lookup endpoint allows developers to get news and headlines breaking on X. This endpoint supports app-auth an +- [Search News](https://docs.x.com/x-api/news/search-news.md): Reference documentation for the endpoint and related functionality. + +## Posts +- [Create Or Edit Post](https://docs.x.com/x-api/posts/create-or-edit-post.md): Reference documentation for the endpoint and related functionality. +- [Create Post](https://docs.x.com/x-api/posts/create-post.md): Reference documentation for the endpoint and related functionality. +- [Delete Post](https://docs.x.com/x-api/posts/delete-post.md): Reference documentation for the endpoint and related functionality. +- [Get 28 Hour Post Insights](https://docs.x.com/x-api/posts/get-28-hour-post-insights.md): Reference documentation for the endpoint and related functionality. +- [Get Count Of All Posts](https://docs.x.com/x-api/posts/get-count-of-all-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Count Of Recent Posts](https://docs.x.com/x-api/posts/get-count-of-recent-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Historical Post Insights](https://docs.x.com/x-api/posts/get-historical-post-insights.md): Reference documentation for the endpoint and related functionality. +- [Get Liking Users](https://docs.x.com/x-api/posts/get-liking-users.md): Reference documentation for the endpoint and related functionality. +- [Get Post Analytics](https://docs.x.com/x-api/posts/get-post-analytics.md): Reference documentation for the endpoint and related functionality. +- [Get Post By Id](https://docs.x.com/x-api/posts/get-post-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Posts By Ids](https://docs.x.com/x-api/posts/get-posts-by-ids.md): Reference documentation for the endpoint and related functionality. +- [Get Quoted Posts](https://docs.x.com/x-api/posts/get-quoted-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Reposted By](https://docs.x.com/x-api/posts/get-reposted-by.md): Reference documentation for the endpoint and related functionality. +- [Get Reposts](https://docs.x.com/x-api/posts/get-reposts.md): Reference documentation for the endpoint and related functionality. +- [Hide Reply](https://docs.x.com/x-api/posts/hide-reply.md): Reference documentation for the endpoint and related functionality. +- [Search All Posts](https://docs.x.com/x-api/posts/search-all-posts.md): Reference documentation for the endpoint and related functionality. +- [Search Recent Posts](https://docs.x.com/x-api/posts/search-recent-posts.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/x-api/posts/volume-streams/introduction.md): * 1% sampled stream. * 10% sampled stream. +- [Integration guide](https://docs.x.com/x-api/posts/retweets/integrate.md): This page covers tools and key concepts for integrating the Retweet endpoints. +- [Retweets](https://docs.x.com/x-api/posts/retweets/introduction.md): Retweet and undo retweets, and retrieve retweet information +- [Manage Retweets](https://docs.x.com/x-api/posts/retweets/quickstart/manage-retweets.md): Retweet and undo Retweets using the X API +- [Retweets Lookup](https://docs.x.com/x-api/posts/retweets/quickstart/retweets-lookup.md): Get users who Retweeted a Post +- [Retweets of Me](https://docs.x.com/x-api/posts/retweets/quickstart/retweets-of-me.md): Get your Posts that have been Retweeted +- [Manage Retweets](https://docs.x.com/x-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST statuses/retweet/:id](https://developer. +- [Overview](https://docs.x.com/x-api/posts/retweets/migrate/overview.md): **Retweets lookup** The v2 Retweets lookup endpoint will replace the standard [v1. 1 GET statuses/retweets/:id](https: +- [Retweets lookup](https://docs.x.com/x-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. +- [Likes](https://docs.x.com/x-api/posts/likes/introduction.md): Like and unlike Posts, and retrieve like information +- [Likes Lookup](https://docs.x.com/x-api/posts/likes/quickstart/likes-lookup.md): Get users who liked a Post and Posts liked by a user +- [Manage Likes](https://docs.x.com/x-api/posts/likes/quickstart/manage-likes.md): Like and unlike Posts using the X API +- [Likes lookup](https://docs.x.com/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET favorites/list](https://developer. +- [Manage Likes](https://docs.x.com/x-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST favorites/create](https://developer. +- [Overview](https://docs.x.com/x-api/posts/likes/migrate/overview.md): These guides will focus on the following areas: * **API request parameters** - The X API v2 endpoint introduces a new +- [Apps](https://docs.x.com/x-api/posts/hide-replies/apps.md): Here's a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their +- [Hide Replies](https://docs.x.com/x-api/posts/hide-replies/introduction.md): Hide and unhide replies to Posts you authored +- [Migration guide](https://docs.x.com/x-api/posts/hide-replies/migrate.md): The v2 hide replies endpoint is replacing the Labs hide replies endpoint. If you have code, apps, or tools that use th +- [Quickstart](https://docs.x.com/x-api/posts/hide-replies/quickstart.md): Hide and unhide replies to your Posts +- [Manage replies by topic](https://docs.x.com/x-api/posts/hide-replies/integrate/manage-replies-by-topic.md): Through the hide replies endpoint, you can build integrations to help people and brands keep their conversation on top +- [Manage replies by topic](https://docs.x.com/x-api/posts/hide-replies/integrate/manage-replies-in-realtime.md): With the hide replies endpoint, you can build a workflow to helps your users hide replies that have a very high-probab +- [Integration Guide](https://docs.x.com/x-api/posts/lookup/integrate.md): Key concepts and best practices for integrating Post lookup +- [Post Lookup](https://docs.x.com/x-api/posts/lookup/introduction.md): Retrieve Posts by ID to get details, verify availability, and examine edit history +- [Quickstart](https://docs.x.com/x-api/posts/lookup/quickstart.md): Make your first Post lookup request in minutes +- [Overview](https://docs.x.com/x-api/posts/lookup/migrate/overview.md): The v2 Posts lookup endpoints replace the standard v1. 1 [GET statuses/lookup](https://developer. +- [v1 to v2](https://docs.x.com/x-api/posts/lookup/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 GET statuses/show and GET statuses/lookup, this guide will help you u +- [Integration Guide](https://docs.x.com/x-api/posts/timelines/integrate.md): Key concepts and best practices for integrating Timelines endpoints +- [Timelines](https://docs.x.com/x-api/posts/timelines/introduction.md): Retrieve Posts from user timelines and home feeds +- [Home Timeline Quickstart](https://docs.x.com/x-api/posts/timelines/quickstart/reverse-chron-quickstart.md): Get a user's home timeline in reverse chronological order +- [User Mentions Timeline](https://docs.x.com/x-api/posts/timelines/quickstart/user-mention-quickstart.md): Get Posts that mention a specific user +- [Overview](https://docs.x.com/x-api/posts/timelines/migrate/overview.md): The v2 reverse chronological timeline, user Posts timeline, and user mention timeline endpoints replace the [v1. 1 sta +- [v1 to v2](https://docs.x.com/x-api/posts/timelines/migrate/standard-to-twitter-api-v2.md): If you have been working with the v1. 1 timelines endpoints (statuses/user\_timeline and statuses/mentions\_timeline), +- [Search Posts](https://docs.x.com/x-api/posts/search/introduction.md): Search the full X archive or recent Posts using advanced operators for keywords, hashtags, users, geo, language, engag +- [Build a query](https://docs.x.com/x-api/posts/search/integrate/build-a-query.md): Learn how to build search queries using operators +- [Search Operators](https://docs.x.com/x-api/posts/search/integrate/operators.md): Complete list of operators for Search queries +- [Integration Guide](https://docs.x.com/x-api/posts/search/integrate/overview.md): Key concepts and best practices for integrating Search Posts +- [Pagination](https://docs.x.com/x-api/posts/search/integrate/paginate.md): Search queries typically match on more Posts than can be returned in a single API response. When that happens, the dat +- [Full-Archive Search Quickstart](https://docs.x.com/x-api/posts/search/quickstart/full-archive-search.md): Search the complete Post archive back to 2006 +- [Recent Search Quickstart](https://docs.x.com/x-api/posts/search/quickstart/recent-search.md): Make your first recent search request in minutes +- [v1 to v2 (Enterprise)](https://docs.x.com/x-api/posts/search/migrate/enterprise-to-twitter-api-v2.md): **Similarities** * Pagination * Timezone * Support for Post edit history and metadata. **Differences** * Endpoint URLs +- [Overview](https://docs.x.com/x-api/posts/search/migrate/overview.md): The v2 Search Tweets endpoint will eventually replace the [standard v1. 1 search/posts](/x-api/posts/search/introducti +- [v1 to v2](https://docs.x.com/x-api/posts/search/migrate/standard-to-twitter-api-v2.md): If you have been working with the v1. 1 [search/posts](/x-api/posts/search/introduction), the goal of this guide is to +- [Integration guide](https://docs.x.com/x-api/posts/bookmarks/integrate.md): This page contains information on several tools and critical concepts that you should know as you integrate the manage +- [Bookmarks](https://docs.x.com/x-api/posts/bookmarks/introduction.md): Save and manage bookmarked Posts for the authenticated user +- [Bookmarks Lookup](https://docs.x.com/x-api/posts/bookmarks/quickstart/bookmarks-lookup.md): Retrieve your bookmarked Posts +- [Manage Bookmarks](https://docs.x.com/x-api/posts/bookmarks/quickstart/manage-bookmarks.md): Add and remove bookmarks using the X API +- [Quote Posts](https://docs.x.com/x-api/posts/quote-tweets/introduction.md): Retrieve Quote Posts for a specific Post +- [Quickstart](https://docs.x.com/x-api/posts/quote-tweets/quickstart.md): Retrieve Quote Posts for a specific Post +- [Filtered Stream](https://docs.x.com/x-api/posts/filtered-stream/introduction.md): Stream near real-time Posts matching your filter rules +- [Quickstart](https://docs.x.com/x-api/posts/filtered-stream/quickstart.md): Connect to the filtered stream and receive near real-time Posts +- [Build a rule](https://docs.x.com/x-api/posts/filtered-stream/integrate/build-a-rule.md): Learn how to build filtered stream rules using operators +- [Matching Posts to Rules](https://docs.x.com/x-api/posts/filtered-stream/integrate/matching-returned-tweets.md): The filtered stream endpoint gives you the ability to have multiple rules in place through a single connection. Before +- [Filtered Stream Operators](https://docs.x.com/x-api/posts/filtered-stream/integrate/operators.md): Complete list of operators for Filtered Stream rules +- [Overview](https://docs.x.com/x-api/posts/filtered-stream/migrate/overview.md): The v2 filtered stream endpoints group is replacing the [standard v1. 1 statuses/filter](https://developer. +- [v1 to v2 (Enterprise)](https://docs.x.com/x-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.md): Use this migration guide to understand the similarities and differences between [PowerTrack API](/x-api/enterprise-gni +- [v1 to v2](https://docs.x.com/x-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.md): If you have been working with the v1. 1 [statuses/filter](https://developer. +- [Post Counts](https://docs.x.com/x-api/posts/counts/introduction.md): Get Post volume data for queries without retrieving the Posts themselves +- [Build a query](https://docs.x.com/x-api/posts/counts/integrate/build-a-query.md): **Query limitations! ** Your queries will be limited depending on which [access level](/x-api/getting-started/about-x- +- [Overview](https://docs.x.com/x-api/posts/counts/integrate/overview.md): This page covers tools and key concepts for integrating the Post counts endpoints. +- [Full-Archive Post Counts](https://docs.x.com/x-api/posts/counts/quickstart/full-archive-tweet-counts.md): Get historical Post volume back to 2006 +- [Recent Post Counts](https://docs.x.com/x-api/posts/counts/quickstart/recent-tweet-counts.md): Get Post volume for the last 7 days +- [v1 to v2 (Enterprise)](https://docs.x.com/x-api/posts/counts/migrate/enterprise-to-twitter-api-v2.md): **Similarities** * Granularity * Pagination * Timezone **Differences** * Endpoint URLs * App and Project requirement * +- [Overview](https://docs.x.com/x-api/posts/counts/migrate/overview.md): The v2 Post counts endpoint will eventually replace the [enterprise Search API’s counts endpoint](/x-api/enterprise-gn +- [Integration guide](https://docs.x.com/x-api/posts/manage-tweets/integrate.md): This page covers tools and key concepts for integrating the manage Posts endpoints into your system. +- [Manage Posts](https://docs.x.com/x-api/posts/manage-tweets/introduction.md): Create and delete Posts on behalf of authenticated users +- [Quickstart](https://docs.x.com/x-api/posts/manage-tweets/quickstart.md): Create and delete Posts using the X API +- [Overview](https://docs.x.com/x-api/posts/manage-tweets/migrate/overview.md): The v2 manage Posts endpoints will replace the standard v1. 1 [POST statuses/update](https://developer. +- [v1 to v2](https://docs.x.com/x-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST statuses/update](https://developer. + +## Powerstream +- [Handling disconnections](https://docs.x.com/x-api/powerstream/handling-disconnections.md): This page covers Powerstream-specific disconnection handling. For comprehensive guidance on handling disconnections ac +- [Introduction](https://docs.x.com/x-api/powerstream/introduction.md): Powerstream is our **lowest-latency streaming API** for accessing public X data in real-time. Unlike other streaming e +- [Powerstream Operators](https://docs.x.com/x-api/powerstream/operators.md): Complete list of operators for Powerstream filtering rules +- [Recovery and redundancy](https://docs.x.com/x-api/powerstream/recovery-and-redundancy.md): This page covers Powerstream-specific recovery and redundancy features. For comprehensive guidance on recovery and red + +## Spaces +- [Get Space By Id](https://docs.x.com/x-api/spaces/get-space-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Space Posts](https://docs.x.com/x-api/spaces/get-space-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Space Ticket Buyers](https://docs.x.com/x-api/spaces/get-space-ticket-buyers.md): Reference documentation for the endpoint and related functionality. +- [Get Spaces By Creator Ids](https://docs.x.com/x-api/spaces/get-spaces-by-creator-ids.md): Reference documentation for the endpoint and related functionality. +- [Get Spaces By Ids](https://docs.x.com/x-api/spaces/get-spaces-by-ids.md): Reference documentation for the endpoint and related functionality. +- [Introduction](https://docs.x.com/x-api/spaces/introduction.md): import { Button } from '/snippets/button.mdx'; The following page describes the Spaces endpoints included in the X AP +- [Search Spaces](https://docs.x.com/x-api/spaces/search-spaces.md): Reference documentation for the endpoint and related functionality. +- [Spaces Lookup](https://docs.x.com/x-api/spaces/lookup/introduction.md): Retrieve Space details by ID or find Spaces by their creators +- [Quickstart](https://docs.x.com/x-api/spaces/lookup/quickstart.md): Retrieve Space details by ID or creator +- [Spaces Search](https://docs.x.com/x-api/spaces/search/introduction.md): Search for live or scheduled Spaces by keyword +- [Quickstart](https://docs.x.com/x-api/spaces/search/quickstart.md): Search for Spaces by keyword + +## Stream +- [Get Stream Rule Counts](https://docs.x.com/x-api/stream/get-stream-rule-counts.md): Reference documentation for the endpoint and related functionality. +- [Get Stream Rules](https://docs.x.com/x-api/stream/get-stream-rules.md): Reference documentation for the endpoint and related functionality. +- [Likes Streams](https://docs.x.com/x-api/stream/likes-streams-introduction.md): Stream real-time like events from across X +- [Stream 10 Sampled Posts](https://docs.x.com/x-api/stream/stream-10-sampled-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream All Likes](https://docs.x.com/x-api/stream/stream-all-likes.md): Reference documentation for the endpoint and related functionality. +- [Stream All Posts](https://docs.x.com/x-api/stream/stream-all-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream English Posts](https://docs.x.com/x-api/stream/stream-english-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Filtered Posts](https://docs.x.com/x-api/stream/stream-filtered-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Japanese Posts](https://docs.x.com/x-api/stream/stream-japanese-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Korean Posts](https://docs.x.com/x-api/stream/stream-korean-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Likes Compliance Data](https://docs.x.com/x-api/stream/stream-likes-compliance-data.md): Reference documentation for the endpoint and related functionality. +- [Stream Portuguese Posts](https://docs.x.com/x-api/stream/stream-portuguese-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Post Labels](https://docs.x.com/x-api/stream/stream-post-labels.md): Reference documentation for the endpoint and related functionality. +- [Stream Posts Compliance Data](https://docs.x.com/x-api/stream/stream-posts-compliance-data.md): Reference documentation for the endpoint and related functionality. +- [Stream Sampled Likes](https://docs.x.com/x-api/stream/stream-sampled-likes.md): Reference documentation for the endpoint and related functionality. +- [Stream Sampled Posts](https://docs.x.com/x-api/stream/stream-sampled-posts.md): Reference documentation for the endpoint and related functionality. +- [Stream Users Compliance Data](https://docs.x.com/x-api/stream/stream-users-compliance-data.md): Reference documentation for the endpoint and related functionality. +- [Update Stream Rules](https://docs.x.com/x-api/stream/update-stream-rules.md): Reference documentation for the endpoint and related functionality. + +## Trends +- [Get Ai Trends By Id](https://docs.x.com/x-api/trends/get-ai-trends-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get Personalized Trends](https://docs.x.com/x-api/trends/get-personalized-trends.md): Reference documentation for the endpoint and related functionality. +- [Get Trends By Woeid](https://docs.x.com/x-api/trends/get-trends-by-woeid.md): Reference documentation for the endpoint and related functionality. +- [Trends by WOEID](https://docs.x.com/x-api/trends/trends-by-woeid/introduction.md): Get trending topics for a specific geographic location +- [Personalized Trends](https://docs.x.com/x-api/trends/personalized-trends/introduction.md): Get trending topics personalized for the authenticated user + +## Usage +- [Get Usage](https://docs.x.com/x-api/usage/get-usage.md): Reference documentation for the endpoint and related functionality. +- [Usage](https://docs.x.com/x-api/usage/introduction.md): Monitor your API usage and track Post consumption + +## Users +- [Block Dms](https://docs.x.com/x-api/users/block-dms.md): Reference documentation for the endpoint and related functionality. +- [Create Bookmark](https://docs.x.com/x-api/users/create-bookmark.md): Reference documentation for the endpoint and related functionality. +- [Delete Bookmark](https://docs.x.com/x-api/users/delete-bookmark.md): Reference documentation for the endpoint and related functionality. +- [Follow List](https://docs.x.com/x-api/users/follow-list.md): Reference documentation for the endpoint and related functionality. +- [Follow User](https://docs.x.com/x-api/users/follow-user.md): Reference documentation for the endpoint and related functionality. +- [Get Affiliates](https://docs.x.com/x-api/users/get-affiliates.md): Reference documentation for the endpoint and related functionality. +- [Get Blocking](https://docs.x.com/x-api/users/get-blocking.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmark Folders](https://docs.x.com/x-api/users/get-bookmark-folders.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmarks By Folder Id](https://docs.x.com/x-api/users/get-bookmarks-by-folder-id.md): Reference documentation for the endpoint and related functionality. +- [Get Bookmarks](https://docs.x.com/x-api/users/get-bookmarks.md): Reference documentation for the endpoint and related functionality. +- [Get Followed Lists](https://docs.x.com/x-api/users/get-followed-lists.md): Reference documentation for the endpoint and related functionality. +- [Get Followers](https://docs.x.com/x-api/users/get-followers.md): Reference documentation for the endpoint and related functionality. +- [Get Following](https://docs.x.com/x-api/users/get-following.md): Reference documentation for the endpoint and related functionality. +- [Get Liked Posts](https://docs.x.com/x-api/users/get-liked-posts.md): Reference documentation for the endpoint and related functionality. +- [Get List Memberships](https://docs.x.com/x-api/users/get-list-memberships.md): Reference documentation for the endpoint and related functionality. +- [Get Mentions](https://docs.x.com/x-api/users/get-mentions.md): Reference documentation for the endpoint and related functionality. +- [Get Muting](https://docs.x.com/x-api/users/get-muting.md): Reference documentation for the endpoint and related functionality. +- [Get My User](https://docs.x.com/x-api/users/get-my-user.md): Reference documentation for the endpoint and related functionality. +- [Get Owned Lists](https://docs.x.com/x-api/users/get-owned-lists.md): Reference documentation for the endpoint and related functionality. +- [Get Pinned Lists](https://docs.x.com/x-api/users/get-pinned-lists.md): Reference documentation for the endpoint and related functionality. +- [Get Posts](https://docs.x.com/x-api/users/get-posts.md): Reference documentation for the endpoint and related functionality. +- [Get Public Keys For Multiple Users](https://docs.x.com/x-api/users/get-public-keys-for-multiple-users.md): Reference documentation for the endpoint and related functionality. +- [Get Reposts Of Me](https://docs.x.com/x-api/users/get-reposts-of-me.md): Reference documentation for the endpoint and related functionality. +- [Get Timeline](https://docs.x.com/x-api/users/get-timeline.md): Reference documentation for the endpoint and related functionality. +- [Get User By Id](https://docs.x.com/x-api/users/get-user-by-id.md): Reference documentation for the endpoint and related functionality. +- [Get User By Username](https://docs.x.com/x-api/users/get-user-by-username.md): Reference documentation for the endpoint and related functionality. +- [Get User Public Keys](https://docs.x.com/x-api/users/get-user-public-keys.md): Reference documentation for the endpoint and related functionality. +- [Get Users By Ids](https://docs.x.com/x-api/users/get-users-by-ids.md): Reference documentation for the endpoint and related functionality. +- [Get Users By Usernames](https://docs.x.com/x-api/users/get-users-by-usernames.md): Reference documentation for the endpoint and related functionality. +- [Like Post](https://docs.x.com/x-api/users/like-post.md): Reference documentation for the endpoint and related functionality. +- [Mute User](https://docs.x.com/x-api/users/mute-user.md): Reference documentation for the endpoint and related functionality. +- [Pin List](https://docs.x.com/x-api/users/pin-list.md): Reference documentation for the endpoint and related functionality. +- [Repost Post](https://docs.x.com/x-api/users/repost-post.md): Reference documentation for the endpoint and related functionality. +- [Search Users](https://docs.x.com/x-api/users/search-users.md): Reference documentation for the endpoint and related functionality. +- [Unblock Dms](https://docs.x.com/x-api/users/unblock-dms.md): Reference documentation for the endpoint and related functionality. +- [Unfollow List](https://docs.x.com/x-api/users/unfollow-list.md): Reference documentation for the endpoint and related functionality. +- [Unfollow User](https://docs.x.com/x-api/users/unfollow-user.md): Reference documentation for the endpoint and related functionality. +- [Unlike Post](https://docs.x.com/x-api/users/unlike-post.md): Reference documentation for the endpoint and related functionality. +- [Unmute User](https://docs.x.com/x-api/users/unmute-user.md): Reference documentation for the endpoint and related functionality. +- [Unpin List](https://docs.x.com/x-api/users/unpin-list.md): Reference documentation for the endpoint and related functionality. +- [Unrepost Post](https://docs.x.com/x-api/users/unrepost-post.md): Reference documentation for the endpoint and related functionality. +- [Integration Guide](https://docs.x.com/x-api/users/blocks/integrate.md): Key concepts and best practices for integrating blocks endpoints +- [Blocks](https://docs.x.com/x-api/users/blocks/introduction.md): Block and unblock users, and retrieve blocked user lists +- [Migration guide](https://docs.x.com/x-api/users/blocks/migrate.md): If you have been working with the standard v1. 1 [GET blocks/ids](https://developer. +- [Quickstart](https://docs.x.com/x-api/users/blocks/quickstart.md): Block and unblock users, and retrieve your block list +- [Integration Guide](https://docs.x.com/x-api/users/mutes/integrate.md): Key concepts and best practices for integrating mutes endpoints +- [Mutes](https://docs.x.com/x-api/users/mutes/introduction.md): Mute and unmute users, and retrieve muted user lists +- [Manage Mutes](https://docs.x.com/x-api/users/mutes/quickstart/manage-mutes-quickstart.md): Mute and unmute users using the X API +- [Mutes Lookup](https://docs.x.com/x-api/users/mutes/quickstart/mutes-lookup.md): Get the list of users you have muted +- [Manage mutes](https://docs.x.com/x-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST mutes/users/create](https://developer. +- [Mutes lookup](https://docs.x.com/x-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET mutes/users/ids](https://developer. +- [Overview](https://docs.x.com/x-api/users/mutes/migrate/overview.md): The v2 mutes lookup endpoint will replace the standard [v1. 1 GET mutes/users/ids](https://developer. +- [Integration Guide](https://docs.x.com/x-api/users/lookup/integrate.md): Key concepts and best practices for integrating User lookup +- [User Lookup](https://docs.x.com/x-api/users/lookup/introduction.md): Retrieve user profiles by ID, username, or for the authenticated user +- [Authenticated User Quickstart](https://docs.x.com/x-api/users/lookup/quickstart/authenticated-lookup.md): Get the currently authenticated user's profile +- [User Lookup Quickstart](https://docs.x.com/x-api/users/lookup/quickstart/user-lookup.md): Look up users by ID or username +- [Overview](https://docs.x.com/x-api/users/lookup/migrate/overview.md): The v2 user lookup endpoints will replace the standard v1. 1 [GET users/lookup](https://developer. +- [v1 to v2](https://docs.x.com/x-api/users/lookup/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 GET users/show and GET users/lookup, the goal of this guide is to hel +- [User Search](https://docs.x.com/x-api/users/search/introduction.md): Search for users by keyword +- [Follows](https://docs.x.com/x-api/users/follows/introduction.md): Manage follows and retrieve follower/following information +- [Quickstart](https://docs.x.com/x-api/users/follows/quickstart.md): Get followers and following lists, and manage follows +- [Overview](https://docs.x.com/x-api/users/follows/migrate/overview.md): The v2 follows lookup endpoints will replace the standard v1. 1 [followers/ids](https://developer. +- [v1 to v2](https://docs.x.com/x-api/users/follows/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST friendships/create](https://developer. + +## Webhooks +- [Create Replay Job For Webhook](https://docs.x.com/x-api/webhooks/create-replay-job-for-webhook.md): Reference documentation for the endpoint and related functionality. +- [Create Stream Link](https://docs.x.com/x-api/webhooks/create-stream-link.md): Reference documentation for the endpoint and related functionality. +- [Create Webhook](https://docs.x.com/x-api/webhooks/create-webhook.md): Reference documentation for the endpoint and related functionality. +- [Delete Stream Link](https://docs.x.com/x-api/webhooks/delete-stream-link.md): Reference documentation for the endpoint and related functionality. +- [Delete Webhook](https://docs.x.com/x-api/webhooks/delete-webhook.md): Reference documentation for the endpoint and related functionality. +- [Get Stream Links](https://docs.x.com/x-api/webhooks/get-stream-links.md): Reference documentation for the endpoint and related functionality. +- [Get Webhook](https://docs.x.com/x-api/webhooks/get-webhook.md): Reference documentation for the endpoint and related functionality. +- [V2 Webhooks API](https://docs.x.com/x-api/webhooks/introduction.md): Receive real-time event notifications from X via webhook-based JSON messages +- [Quickstart](https://docs.x.com/x-api/webhooks/quickstart.md): Set up your webhook consumer app, implement CRC validation, and start receiving events +- [Validate Webhook](https://docs.x.com/x-api/webhooks/validate-webhook.md): Reference documentation for the endpoint and related functionality. +- [Filtered Stream Webhooks API](https://docs.x.com/x-api/webhooks/stream/introduction.md): The filtered stream endpoint group enables developers to filter a stream of public Posts. This endpoint group’s functi +- [Quickstart](https://docs.x.com/x-api/webhooks/stream/quickstart.md): The v2 filtered stream webhooks API is similar to the [v2 filtered stream endpoint](/x-api/posts/filtered-stream/intro + +## Full Documentation +- [llms-full.txt](https://docs.x.com/llms-full.txt) \ No newline at end of file diff --git a/x-api/marketplace/get-marketplace-handle-availability.mdx b/x-api/marketplace/get-marketplace-handle-availability.mdx index 618c8e1e7..40728fe0c 100644 --- a/x-api/marketplace/get-marketplace-handle-availability.mdx +++ b/x-api/marketplace/get-marketplace-handle-availability.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/marketplace/handles/{handle}/availability ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/append-media-upload.mdx b/x-api/media/append-media-upload.mdx index 42dcb1156..22746b60a 100644 --- a/x-api/media/append-media-upload.mdx +++ b/x-api/media/append-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/upload/{id}/append ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/create-media-metadata.mdx b/x-api/media/create-media-metadata.mdx index f8b4bdcb9..b3e829bb2 100644 --- a/x-api/media/create-media-metadata.mdx +++ b/x-api/media/create-media-metadata.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/metadata ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/create-media-subtitles.mdx b/x-api/media/create-media-subtitles.mdx index dbb9f3f21..7903ab533 100644 --- a/x-api/media/create-media-subtitles.mdx +++ b/x-api/media/create-media-subtitles.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/subtitles ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/delete-media-subtitles.mdx b/x-api/media/delete-media-subtitles.mdx index 4a616660b..68ed298d3 100644 --- a/x-api/media/delete-media-subtitles.mdx +++ b/x-api/media/delete-media-subtitles.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/media/subtitles ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/finalize-media-upload.mdx b/x-api/media/finalize-media-upload.mdx index 4f9c0e41a..25fd59532 100644 --- a/x-api/media/finalize-media-upload.mdx +++ b/x-api/media/finalize-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/upload/{id}/finalize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/get-media-analytics.mdx b/x-api/media/get-media-analytics.mdx index fea9da1e0..b9a7ab6a1 100644 --- a/x-api/media/get-media-analytics.mdx +++ b/x-api/media/get-media-analytics.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/media/analytics ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/get-media-by-media-key.mdx b/x-api/media/get-media-by-media-key.mdx index 416c1dc33..4bffbc21a 100644 --- a/x-api/media/get-media-by-media-key.mdx +++ b/x-api/media/get-media-by-media-key.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/media/{media_key} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/get-media-by-media-keys.mdx b/x-api/media/get-media-by-media-keys.mdx index 0e8b121c8..670174ff2 100644 --- a/x-api/media/get-media-by-media-keys.mdx +++ b/x-api/media/get-media-by-media-keys.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/media ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/get-media-upload-status.mdx b/x-api/media/get-media-upload-status.mdx index be28f5a45..97583a916 100644 --- a/x-api/media/get-media-upload-status.mdx +++ b/x-api/media/get-media-upload-status.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/media/upload ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/initialize-media-upload.mdx b/x-api/media/initialize-media-upload.mdx index 150143a2d..39dbb0a4c 100644 --- a/x-api/media/initialize-media-upload.mdx +++ b/x-api/media/initialize-media-upload.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/upload/initialize ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/media/introduction.mdx b/x-api/media/introduction.mdx index 73b6d4bb5..96600c26c 100644 --- a/x-api/media/introduction.mdx +++ b/x-api/media/introduction.mdx @@ -2,6 +2,8 @@ title: Introduction sidebarTitle: Introduction keywords: ["media", "media upload", "images", "videos", "GIF", "media API", "upload media", "media objects", "media ID"] + +description: A media object represents a single photo, video or animated GIF. Media objects are used by many endpoints within the X API, and may be included in Posts, Dir... --- A media object represents a single photo, video or animated GIF. Media objects are used by many endpoints within the X API, and may be included in Posts, Direct Messages, user profiles, advertising creatives and elsewhere. Each media object may have multiple display or playback variants, with different resolutions or formats. diff --git a/x-api/media/quickstart/best-practices.mdx b/x-api/media/quickstart/best-practices.mdx index b772362ca..2cdbf6feb 100644 --- a/x-api/media/quickstart/best-practices.mdx +++ b/x-api/media/quickstart/best-practices.mdx @@ -2,7 +2,8 @@ title: Best practices sidebarTitle: Best practices keywords: ["media upload best practices", "upload media", "media best practices", "image upload", "video upload", "media upload guide"] ---- + +description: There are a few important concepts to understand when using the [`POST /2/media/upload`](/x-api/media/media-upload) endpoint. Uploading media with OAuth...--- There are a few important concepts to understand when using the [`POST /2/media/upload`](/x-api/media/media-upload) endpoint. Uploading media with OAuth can be a bit tricky, so we’ve outlined some things to keep in mind as well as a working sample of how to use this endpoint here. diff --git a/x-api/media/upload-media.mdx b/x-api/media/upload-media.mdx index e6aa3e6e8..4a6cab1ef 100644 --- a/x-api/media/upload-media.mdx +++ b/x-api/media/upload-media.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/media/upload ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/migrate/data-format-migration.mdx b/x-api/migrate/data-format-migration.mdx index 5dbec96c7..848cb37a6 100644 --- a/x-api/migrate/data-format-migration.mdx +++ b/x-api/migrate/data-format-migration.mdx @@ -1,6 +1,7 @@ --- title: Data Formation Migration keywords: ["data format migration", "data migration", "format changes", "data structure migration", "migrate data format"] + --- import { Button } from '/snippets/button.mdx'; @@ -20,912 +21,4 @@ You may also be interested in our [visual data format migration tool](/x-api/mig #### Requesting objects and fields -One of the biggest changes between the pre-v2 endpoints and v2 is that the newer version only returns a few fields by default, whereas standard, premium, and enterprise endpoints deliver most fields by default. The new version uses parameters called [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) to specifically request additional data beyond the defaults, meaning that you can request just the data you need without having to ingest fields that don’t matter to you.  - -Any fields that you request that relate to the primary data object will return in that primary data object along with the default values. However, if you request any expanded objects using the expansions parameter, the secondary objects will return in a new includes object. You can match the expanded objects in the includes object back to the primary object by using the ID field which will return in both. - -For example, if you are using the v2 [Post lookup](/x-api/posts/lookup/introduction) endpoint and you include the expansions=author_id parameter in your request, you will receive the author_id field within the primary Post object, as well as a user object per Post in the includes object, each of which will include the default id field that can be used to match the user object back to the Post object. Here is an example of what this looks like: - -``` -{ - "data": [ - { - "author_id": "2244994945", - "id": "1397568983931392004", - "text": "The Twitter Developer Platform. Ooh la la! https://t.co/iGTdPXBfOv https://t.co/Ze8z8EODdg" - } - ], - "includes": { - "users": [ - { - "id": "2244994945", - "name": "Twitter Dev", - "username": "TwitterDev" - } - ] - } -} -``` - - -#### Updated JSON design - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a **statuses** array, while X API v2 returns a **data** array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as **contributors** and **user.translator_type** are being removed.  -* Instead of using both **favorites** (in Post object) and **favourites** (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.  -   - -#### New v2 fields - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - - -### Migrating from standard v1.1's data format to v2 - -If you haven't already, we recommend that you read through the [data formats migration](/x-api/migrate/data-format-migration) introduction to start. You may also be interested in our [visual data format migration tool](/x-api/migrate/data-format-migration#visual-data-format-migration-tool) to help you quickly see the differences between the [X API v1.1 data format](https://developer.x.com/en/docs/x-api/v1/data-dictionary/overview) and the [X API v2 format](/x-api/fundamentals/data-dictionary). - -The standard v1.1 data format, also known as the native format, is the primary format that delivers with the [standard v1.1](https://developer.x.com/en/docs/twitter-api/v1) endpoints. - -If you are using the premium product, please refer to the [native enriched guide](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2). Enterprise clients might be using native enriched or activity streams, depending on how you are set up within the Gnip console.  - -#### Standard v1.1 vs v2 payload structure - -The following table displays the high-level objects and format that you can expect to receive from v2 compared to the v1.1 format. - -| | **v1.1 structure** | **v2 structure** | -| :--- | :--- | :--- | -| **Default** | \{
~all tweet object fields~,
"entities": \{
"hashtags": \[\],
"symbols": \[\],
"user_mentions": \[\],
"urls": \[\],
"media": \[\]
},
"extended_entities": {},
"user": {},
"place": {},
"retweeted\_status/quoted\_status"
} | \{
"data": \[\{
"id",
"text",

"edit\_history\_tweet_ids"
}\]
} | -| **With defined [field and expansion](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) parameters** | | \{
"data": \[\{
~tweet object fields~,
"entities": \{
"hashtags": \[\],
"cashtags": \[\],
"mentions": \[\],
"urls": \[\],
},
"attachments": \{

"media_keys": \[\],

"poll_ids": \[\]

}
}\],
"includes": \[
"tweets": \[~tweet objects~\],
"users": \[~user objects~\],
"media": \[~media objects~\],
"places": \[~place object~\],

"polls": \[~poll object~\]
\],

"matching_rules": \[\]
} | - - -**Field mapping** - -The following section describes which v1.1 fields map to v2 fields, as well as which v2 parameters are required to receive the new field. -  - -#### Tweet object - -| | | | -| :--- | :--- | :--- | -| **Twitter 1.1 format** | **Twitter v2 format** | **Required v2 parameters** | -| created_at | data.created_at | tweet.fields=created_at | -| id | | N/A id is a string | -| id_str | data.id | default | -| text | data.text | default | -| full_text | | N/A text includes the complete text | -| truncated | | N/A text includes the complete text | -| display\_text\_range | | N/A text includes the complete text | -| edit_history | data.edit\_history\_tweet_ids | default | -| edit_controls | data.edit_controls | tweet.fields=edit_controls | -| editable | data.edit\_controls.is\_edit_eligible | tweet.fields=edit_controls | -| entities | data.entities | tweet.fields=entities | -| entities.user_mentions | data.entities.mentions | tweet.fields=entities | -| entities.symbols | data.entities.cashtags | tweet.fields=entities | -| entities.hashtags | data.entities.hashtags | tweet.fields=entities | -| entities.urls | data.entities.urls | tweet.fields=entities | -| entities.media | includes.media | expansions=attachments.media_keys | -| extended_entities | data.attachments | tweet_fields=attachments | -| in\_reply\_to\_status\_id | | N/A referenced_tweets.id is a string | -| in\_reply\_to\_status\_id_str | data.referenced_tweets.id (if type=replied_to) | expansions=referenced_tweets.id | -| in\_reply\_to\_user\_id | | N/A in\_reply\_to\_user\_id is a string | -| in\_reply\_to\_user\_id_str | data.in\_reply\_to\_user\_id | tweet.fields=in\_reply\_to\_user\_id | -| in\_reply\_to\_screen\_name | includes.users..username | tweet.fields=in\_reply\_to\_user\_id&expansions=entities.mentions.username | -| user | includes.users | expansions=author_id | -| geo | data.geo.place_id | tweet.fields=geo | -| coordinates | data.geo.place_id | expansions=geo.place_id | -| place | data.geo.place_id | expansions=geo.place_id | -| retweeted_status | data.referenced_tweets.id (if type=retweeted) | expansions=referenced_tweets.id | -| is\_quoted\_status | | Not available | -| quoted\_status\_id | | N/A referenced_tweets.id is a string | -| quoted\_status\_id_str | data.referenced_tweets.id (if type=quoted) | expansions=referenced_tweets.id | -| quoted\_status\_permalink | | Not Available | -| quoted_status | data.referenced_tweets (if type=quoted) | expansions=referenced_tweets.id | -| retweet_count | data.public\_metrics.retweet\_count | tweet.fields=public_metrics | -| favorite_count | data.public\_metrics.like\_count | tweet.fields=public_metrics | -| favorited | | Not available | -| retweeted | | Not available | -| possibly_sensitive | data.possibly_sensitive | tweet.fields=possibly_sensitive | -| lang | data.lang | tweet.fields=lang | -| scopes | | Not available | -| withheld | data.withheld | tweet.fields=withheld | - -**Example** - -| | | -| :--- | :--- | -| **Tweet object in 1.1**

Example URI with parameters:

https://api.x.com/1.1/statuses/lookup.json?id=1359554366051504129&tweet_mode=extended | **Tweet object and request with v2**

Example URI with parameters:

https://api.x.com/2/tweets?ids=1359554366051504129&tweet.fields=attachments,author\_id,context\_annotations,conversation\_id,created\_at,entities,geo,id,in\_reply\_to\_user\_id,lang,possibly\_sensitive,public\_metrics,referenced\_tweets,reply\_settings,text,withheld | -| \{
"created_at": "Wed Feb 10 17:26:34 +0000 2021",
"id": 1359554366051504129,
"id_str": "1359554366051504129",
"text": "Go ahead, follow another puppy account. We won’t judge. \\n\\nIntroducing the manage follows endpoints to the new… https:\\/\\/t.co\\/3cBZKZUevF",
"truncated": true,
"entities": \{
"hashtags": \[\],
"symbols": \[\],
"user_mentions": \[\],
"urls": \[\{
"url": "https:\\/\\/t.co\\/3cBZKZUevF",
"expanded_url": "https:\\/\\/twitter.com\\/i\\/web\\/status\\/1359554366051504129",
"display_url": "twitter.com\\/i\\/web\\/status\\/1…",
"indices": \[
111,
134
\]
}\]
},

"in\_reply\_to\_status\_id": null,
"in\_reply\_to\_status\_id_str": null,
"in\_reply\_to\_user\_id": null,
"in\_reply\_to\_user\_id_str": null,
"in\_reply\_to\_screen\_name": null,
"user": \{
...
},
"geo": null,
"coordinates": null,
"place": null,
"contributors": null,
"is\_quote\_status": false,
"retweet_count": 18,
"favorite_count": 98,
"favorited": false,
"retweeted": false,
"possibly_sensitive": false,
"possibly\_sensitive\_appealable": false,
"lang": "en"
} | \{
"data": \[\{
"id": "1359554366051504129",
"text": "Go ahead, follow another puppy account. We won’t judge. \\n\\nIntroducing the manage follows endpoints to the new #TwitterAPI. You can now use the v2 API to follow and unfollow accounts. Learn more https://t.co/mtpd9VIMDa",
"lang": "en",
"conversation_id": "1359554366051504129",
"possibly_sensitive": false,
"reply_settings": "everyone",
"created_at": "2021-02-10T17:26:34.000Z",
"author_id": "2244994945",
"public_metrics": \{
"retweet_count": 18,
"reply_count": 11,
"like_count": 98,
"quote_count": 7
},
"entities": \{
"hashtags": \[\{
"start": 110,
"end": 121,
"tag": "TwitterAPI"
}\],
"urls": \[\{
"start": 194,
"end": 217,
"url": "https://t.co/mtpd9VIMDa",
"expanded_url": "https://devcommunity.x.com/t/introducing-the-new-manage-follows-endpoints-to-the-twitter-api-v2/149465",
"display_url": "devcommunity.com/t/introducing-…",
"images": \[\{
"url": "https://pbs.twimg.com/news\_img/1359554367905427457/DczC72\_\_?format=jpg&name=orig",
"width": 1200,
"height": 630
},
\{
"url": "https://pbs.twimg.com/news\_img/1359554367905427457/DczC72\_\_?format=jpg&name=150x150",
"width": 150,
"height": 150
}
\],
"status": 200,
"title": "Introducing the new manage follows endpoints to the X API v2",
"description": "To follow, or not to follow? You’re now free to answer that question however you like using the X API v2. Today, we’re excited to announce the release of the new manage follows endpoints into the new Twitter API. As teased when we launched the follows lookup endpoints a little over a month ago, the ability to manage follow relationships is finally here. These are some of our most popular endpoints on our v1.1 APIs, so we’re excited to unlock a wide range of use cases on X API v2. W...",
"unwound_url": "https://devcommunity.x.com/t/introducing-the-new-manage-follows-endpoints-to-the-twitter-api-v2/149465"
}\]
},
"context_annotations": \[\{
"domain": \{
"id": "46",
"name": "Brand Category",
"description": "Categories within Brand Verticals that narrow down the scope of Brands"
},
"entity": \{
"id": "781974596752842752",
"name": "Services"
}
},
\{
"domain": \{
"id": "47",
"name": "Brand",
"description": "Brands and Companies"
},
"entity": \{
"id": "10045225402",
"name": "Twitter"
}
}
\]
}\]
} | - -* * * - -#### User object - -| | | | -| :--- | :--- | :--- | -| **Twitter 1.1 format** | **Twitter v2 format** | **Required v2 parameters** | -| user_id | data.author_id | tweet.fields=author_id | -| user.id | | N/A use includes.users.id | -| user.id_str | includes.users.id | expansions=author_id | -| user.name | includes.users.name | expansions=author_id | -| user.screen_name | includes.user.username | expansions=author_id | -| user.location | includes.users.location | expansions=author_id&user.fields=location | -| user.description | includes.users.description | expansions=author_id&user.fields=description | -| user.url | includes.users.url | expansions=author_id&user.fields=entities | -| user.entities | includes.users.entities | | -| user.entities.url.urls.url | includes.users.entities.url.urls.url | | -| user.entities.url.urls.expanded_url | includes.users.entities.url.urls.expanded_url | expansions=author_id&user.fields=entities | -| user.entities.url.urls.display_url | includes.users.entities.url.urls.display_url | expansions=author_id&user.fields=entities | -| user.entities.url.urls.display_url.indicies\[0\] | includes.users.entities.url.urls.start | expansions=author_id&user.fields=entities | -| user.entities.url.urls.display_url.indicies\[1\] | includes.users.entities.url.urls.end | expansions=author_id&user.fields=entities | -| user.protected | includes.users.protected | expansions=author_id&user.fields=protected | -| user.followers_count | includes.users.public\_metrics.followers\_count | expansions=author\_id&user.fields=public\_metrics | -| user.friends_count | includes.users.public\_metrics.following\_count | expansions=author\_id&user.fields=public\_metrics | -| user.listed_count | includes.users.public\_metrics.listed\_count | expansions=author\_id&user.fields=public\_metrics | -| user.created_at | includes.users.created_at | expansions=author\_id&user.fields=created\_at | -| user.favourites_count | | | -| user.verified | includes.users.verified | expansions=author_id&user.fields=verified | -| user.statuses_count | includes.users.public\_metrics.tweet\_count | expansions=author\_id&user.fields=public\_metrics | -| user.profile\_image\_url_https | includes.users.profile\_image\_url | expansions=author\_id&user.fields=profile\_image_url | - -**Example** - -| | | -| :--- | :--- | -| **User object in 1.1** | **User object and request with v2** | -| "user": \{
"id": 2244994945,
"id_str": "2244994945",
"name": "Twitter Dev",
"screen_name": "TwitterDev",
"location": "127.0.0.1",
"description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.",
"url": "https:\\/\\/t.co\\/3ZX3TNiZCY",
"entities": \{
"url": \{
"urls": \[\{
"url": "https:\\/\\/t.co\\/3ZX3TNiZCY",
"expanded_url": "https:\\/\\/developer.x.com\\/en\\/community",
"display_url": "developer.x.com\\/en\\/community",
"indices": \[
0,
23
\]
}\]
},
"description": \{
"urls": \[\]
}
},
"protected": false,
"followers_count": 517232,
"friends_count": 2032,
"listed_count": 1722,
"created_at": "Sat Dec 14 04:35:55 +0000 2013",
"favourites_count": 2134,
"utc_offset": null,
"time_zone": null,
"geo_enabled": true,
"verified": true,
"statuses_count": 3677,
"lang": null,
"contributors_enabled": false,
"is_translator": false,
"is\_translation\_enabled": false,
"profile\_background\_color": "FFFFFF",
"profile\_background\_image_url": "http:\\/\\/abs.twimg.com\\/images\\/themes\\/theme1\\/bg.png",
"profile\_background\_image\_url\_https": "https:\\/\\/abs.twimg.com\\/images\\/themes\\/theme1\\/bg.png",
"profile\_background\_tile": false,
"profile\_image\_url": "http:\\/\\/pbs.twimg.com\\/profile\_images\\/1354494203451961345\\/d8HkZl6p\_normal.jpg",
"profile\_image\_url\_https": "https:\\/\\/pbs.twimg.com\\/profile\_images\\/1354494203451961345\\/d8HkZl6p_normal.jpg",
"profile\_banner\_url": "https:\\/\\/pbs.twimg.com\\/profile_banners\\/2244994945\\/1611792896",
"profile\_link\_color": "0084B4",
"profile\_sidebar\_border_color": "FFFFFF",
"profile\_sidebar\_fill_color": "DDEEF6",
"profile\_text\_color": "333333",
"profile\_use\_background_image": false,
"has\_extended\_profile": true,
"default_profile": false,
"default\_profile\_image": false,
"following": null,
"follow\_request\_sent": null,
"notifications": null,
"translator_type": "regular"
} | \{
"data": \[\{
"author_id": "2244994945",
"id": "1362876655061073928",
"text": "From our living rooms to yours 🐱‍💻🛋️Our developer advocates have some exciting Twitch streams and virtual events planned to help you get started with the new #TwitterAPI. Check out the schedule for details, and let us know if you want to see more!\\n👇\\nhttps://t.co/cixDY9qkvH"
}\],
"includes": \{
"users": \[\{
"public_metrics": \{
"followers_count": 517233,
"following_count": 2034,
"tweet_count": 3677,
"listed_count": 1727
},
"username": "TwitterDev",
"entities": \{
"url": \{
"urls": \[\{
"start": 0,
"end": 23,
"url": "https://t.co/3ZX3TNiZCY",
"expanded_url": "https://developer.x.com/en/community",
"display_url": "developer.x.com/en/community"
}\]
},
"description": \{
"hashtags": \[\{
"start": 17,
"end": 28,
"tag": "TwitterDev"
},
\{
"start": 105,
"end": 116,
"tag": "TwitterAPI"
}
\]
}
},
"description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.",
"name": "Twitter Dev",
"verified": true,
"location": "127.0.0.1",
"id": "2244994945",
"protected": false,
"url": "https://t.co/3ZX3TNiZCY",
"profile\_image\_url": "https://pbs.twimg.com/profile\_images/1354494203451961345/d8HkZl6p\_normal.jpg",
"created_at": "2013-12-14T04:35:55.000Z"
}\]
}
} | - -#### Entities and expanded entities objects - -| | | | | -| :--- | :--- | :--- | :--- | -| **Twitter 1.1 format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| entities | data.entities | tweet.fields=entities | object | -| entities.hashtags | data.entities.hashtags | tweet.fields=entities | array of objects | -| entities.hashtags.indices\[0\] | data.entities.hashtags.start | tweet.fields=entities | number | -| entities.hashtags.indices\[1\] | data.entities.hashtags.end | tweet.fields=entities | number | -| entities.hashtags.text | data.entities.hashtags.tag | tweet.fields=entities | string | -| entities.urls | data.entities.urls | tweet.fields=entities | array of objects | -| entities.urls.indices\[0\] | data.entities.urls.start | tweet.fields=entities | number | -| entities.urls.indices\[1\] | data.entities.urls.end | tweet.fields=entities | number | -| entities.urls.url | data.entities.urls.url | tweet.fields=entities | string | -| entities.user_mentions | data.entities.mentions | tweet.fields=entities | array of objects | -| entities.user_mentions.indicies\[0\] | data.entities.mentions.start | tweet.fields=entities | number | -| entities.user_mentions.indicies\[1\] | data.entities.mentions.end | tweet.fields=entities | number | -| entities.user\_mentions.screen\_name | data.entities.mentions.username | tweet.fields=entities | string | -| entities.symbols | data.entities.cashtags | tweet.fields=entities | array of objects | -| entities.symbols.indices\[0\] | data.entities.cashtags.start | tweet.fields=entities | number | -| entities.symbols.indices\[1\] | data.entities.cashtags.end | tweet.fields=entities | number | -| entities.symbols.text | data.entities.cashtags.tag | tweet.fields=entities | string | -| entities.media | includes.media | expansions=attachments.media_keys | array of objects | -| entities.media.id_str | includes.media.media_key | expansions=attachments.media_keys | string | -| entities.media.type | includes.media.media.type | expansions=attachments.media_keys | string | -| entities.media.media_url | | N/A use includes.media.url | string | -| entities.media.media\_url\_https | includes.media.url | expansions=attachments.media_keys&media.fields=url | string | -| entities.media.url | | | | -| entities.media.display_url | | | | -| entities.media.expanded_url | | | | -| entities.media.media\_url\_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | string | -| extended_entities | data.attachments | tweet_fields=attachments | object | -| extended_entities | data.attachments.media_keys | tweet.fields=attachments | array of objects | -| extended_entities.media | includes.media | expansions=attachments.media_keys | array of objects | -| extended\_entities.media.id\_str | includes.media.media_key | expansions=attachments.media_keys | string | -| extended_entities.media.type | includes.media.media.type | expansions=attachments.media_keys | string | -| extended_entities.media.sizes.thumb.w | | Not Available | | -| extended_entities.media.sizes.thumb.h | | Not Available | | -| extended_entities.media.sizes.thumb.resize | | Not Available | | -| extended_entities.media.sizes.large.w | includes.media.height | expansions=attachments.media_keys&media.fields=height | | -| extended_entities.media.sizes.large.h | includes.media.width | expansions=attachments.media_keys&media.fields=width | | -| extended_entities.media.sizes.large.resize | | Not Available | | -| extended_entities.media.sizes.small.w | | Not Available | | -| extended_entities.media.sizes.small.h | | Not Available | | -| extended_entities.media.sizes.small.resize | | Not Available | | -| extended_entities.media.sizes.medium.w | | Not Available | | -| extended_entities.media.sizes.medium.h | | Not Available | | -| extended_entities.media.sizes.medium.resize | | Not Available | | -| extended\_entities.media.media\_url_https | includes.media.url | expansions=attachments.media_keys&media.fields=url | string | -| extended\_entities.media.media\_url_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | string | -| extended\_entities.media.video\_info.duration_millis | includes.media.duration_ms | expansions=attachments.media\_keys&media.fields=duration\_ms | number | - -**Example** - -| | | -| :--- | :--- | -| **Entities and extended entities in v1.1 (with video)** | **Entities, attachments and includes in v2**

https://api.x.com/2/tweets?ids=1370161532013735937&expansions=attachments.media\_keys,entities.mentions.username&tweet.fields=entities&user.fields=created\_at,description,entities,location,name,profile\_image\_url,protected,public\_metrics,url,username,verified,withheld&media.fields=duration\_ms,height,media\_key,preview\_image\_url,public\_metrics,type,url,width | -| "entities": \{
"hashtags": \[\{
"text": "test",
"indices": \[
8,
13
\]
}\],
"symbols": \[\],
"user_mentions": \[\{
"screen_name": "TwitterDev",
"name": "Twitter Dev",
"id": 2244994945,
"id_str": "2244994945",
"indices": \[
31,
42
\]
}\],
"urls": \[\{
"url": "https:\\/\\/t.co\\/XVLZ3uwikc",
"expanded_url": "https:\\/\\/developer.x.com\\/en",
"display_url": "developer.x.com\\/en",
"indices": \[
91,
114
\]
}\],
"media": \[\{
"id": 1370161464028196868,
"id_str": "1370161464028196868",
"indices": \[
115,
138
\],
"media\_url": "http:\\/\\/pbs.twimg.com\\/ext\_tw\_video\_thumb\\/1370161464028196868\\/pu\\/img\\/cGLCoXBHVktkwlC5.jpg",
"media\_url\_https": "https:\\/\\/pbs.twimg.com\\/ext\_tw\_video_thumb\\/1370161464028196868\\/pu\\/img\\/cGLCoXBHVktkwlC5.jpg",
"url": "https:\\/\\/t.co\\/dz4oByygWA",
"display_url": "pic.x.com\\/dz4oByygWA",
"expanded_url": "https:\\/\\/twitter.com\\/furiouscamper\\/status\\/1370161532013735937\\/video\\/1",
"type": "photo",
"sizes": \{
"thumb": \{
"w": 150,
"h": 150,
"resize": "crop"
},
"small": \{
"w": 383,
"h": 680,
"resize": "fit"
},
"large": \{
"w": 720,
"h": 1280,
"resize": "fit"
},
"medium": \{
"w": 675,
"h": 1200,
"resize": "fit"
}
}
}\]
},
"extended_entities": \{
"media": \[\{
"id": 1370161464028196868,
"id_str": "1370161464028196868",
"indices": \[
115,
138
\],
"media\_url": "http:\\/\\/pbs.twimg.com\\/ext\_tw\_video\_thumb\\/1370161464028196868\\/pu\\/img\\/cGLCoXBHVktkwlC5.jpg",
"media\_url\_https": "https:\\/\\/pbs.twimg.com\\/ext\_tw\_video_thumb\\/1370161464028196868\\/pu\\/img\\/cGLCoXBHVktkwlC5.jpg",
"url": "https:\\/\\/t.co\\/dz4oByygWA",
"display_url": "pic.x.com\\/dz4oByygWA",
"expanded_url": "https:\\/\\/twitter.com\\/furiouscamper\\/status\\/1370161532013735937\\/video\\/1",
"type": "video",
"sizes": \{
"thumb": \{
"w": 150,
"h": 150,
"resize": "crop"
},
"small": \{
"w": 383,
"h": 680,
"resize": "fit"
},
"large": \{
"w": 720,
"h": 1280,
"resize": "fit"
},
"medium": \{
"w": 675,
"h": 1200,
"resize": "fit"
}
},
"video_info": \{
"aspect_ratio": \[
9,
16
\],
"duration_millis": 5140,
"variants": \[\{
"bitrate": 950000,
"content_type": "video\\/mp4",
"url": "https:\\/\\/video.twimg.com\\/ext\_tw\_video\\/1370161464028196868\\/pu\\/vid\\/480x852\\/rAuFVMEqs0MeP4P4.mp4?tag=12"
},
\{
"bitrate": 2176000,
"content_type": "video\\/mp4",
"url": "https:\\/\\/video.twimg.com\\/ext\_tw\_video\\/1370161464028196868\\/pu\\/vid\\/720x1280\\/ZxVL5qYO-DNVuSyq.mp4?tag=12"
},
\{
"content_type": "application\\/x-mpegURL",
"url": "https:\\/\\/video.twimg.com\\/ext\_tw\_video\\/1370161464028196868\\/pu\\/pl\\/EGVpuZpo-wYxTNCq.m3u8?tag=12"
},
\{
"bitrate": 632000,
"content_type": "video\\/mp4",
"url": "https:\\/\\/video.twimg.com\\/ext\_tw\_video\\/1370161464028196868\\/pu\\/vid\\/320x568\\/M7VtocAwKPFdkqzF.mp4?tag=12"
}
\]
},
"additional\_media\_info": \{
"monetizable": false
}
}\]
} | \{
"data": \[\{
"entities": \{
"hashtags": \[\{
"start": 8,
"end": 13,
"tag": "test"
}\],
"mentions": \[\{
"start": 31,
"end": 42,
"username": "TwitterDev"
}\],
"urls": \[\{
"start": 91,
"end": 114,
"url": "https://t.co/XVLZ3uwikc",
"expanded_url": "https://developer.x.com/en",
"display_url": "developer.x.com/en",
"status": 200,
"title": "Use Cases, Tutorials, & Documentation",
"description": "Publish & analyze Tweets, optimize ads, & create unique customer experiences with the Twitter API, Twitter Ads API, & Twitter for Websites. Let's start building.",
"unwound_url": "https://developer.x.com/en"
},
\{
"start": 115,
"end": 138,
"url": "https://t.co/dz4oByygWA",
"expanded_url": "https://x.com/furiouscamper/status/1370161532013735937/video/1",
"display_url": "pic.x.com/dz4oByygWA"
}
\]
},
"id": "1370161532013735937",
"text": "Another #test with a video and @TwitterDev mention. Excited for new format migration docs! https://t.co/XVLZ3uwikc https://t.co/dz4oByygWA",
"attachments": \{
"media_keys": \[
"7_1370161464028196868"
\]
}
}\],
"includes": \{
"media": \[\{
"type": "video",
"height": 1280,
"public_metrics": \{
"view_count": 37
},
"width": 720,
"media\_key": "7\_1370161464028196868",
"duration_ms": 5140,
"preview\_image\_url": "https://pbs.twimg.com/ext\_tw\_video_thumb/1370161464028196868/pu/img/cGLCoXBHVktkwlC5.jpg"
}\],
"users": \[\{
"public_metrics": \{
"followers_count": 517233,
"following_count": 2034,
"tweet_count": 3677,
"listed_count": 1727
},
"created_at": "2013-12-14T04:35:55.000Z",
"profile\_image\_url": "https://pbs.twimg.com/profile\_images/1354494203451961345/d8HkZl6p\_normal.jpg",
"description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.",
"verified": true,
"id": "2244994945",
"username": "TwitterDev",
"protected": false,
"entities": \{
"url": \{
"urls": \[\{
"start": 0,
"end": 23,
"url": "https://t.co/3ZX3TNiZCY",
"expanded_url": "https://developer.x.com/en/community",
"display_url": "developer.x.com/en/community"
}\]
},
"description": \{
"hashtags": \[\{
"start": 17,
"end": 28,
"tag": "TwitterDev"
},
\{
"start": 105,
"end": 116,
"tag": "TwitterAPI"
}
\]
}
},
"url": "https://t.co/3ZX3TNiZCY",
"name": "Twitter Dev",
"location": "127.0.0.1"
}\]
}
} | - -* * * - -#### Place object - -| | | | -| :--- | :--- | :--- | -| **Twitter 1.1 format** | **Twitter v2 format** | **Required v2 parameters** | -| place | data.geo.place_id | tweet.fields=geo | -| place.id | includes.places.id | expansions=geo.place_id | -| place.id.place_type | includes.places.place_type | expansions=geo.place\_id&place.fields=place\_type | -| place.id.name | includes.places.name | expansions=geo.place_id&place.fields=name | -| place.id.full_name | includes.places.full_name | expansions=geo.place_id | -| place.id.country_code | includes.places.country_code | expansions=geo.place\_id&place.fields=country\_code | -| place.id.country | includes.places.country | expansions=geo.place_id&place.fields=country | -| place.id.contained_within | includes.places.contained_within | expansions=geo.place\_id&place.fields=contained\_within | -| place.id.bounding_box.type | includes.places.geo.type | expansions=geo.place\_id&place.fields=place\_type | -| place.id.bounding_box.coordinates | includes.places.geo.bbox | expansions=geo.place_id&place.fields=geo | -| place.id.attributes | includes.places.properties | expansions=geo.place_id&place.fields=geo | - -**Example** - -| | | -| :--- | :--- | -| **Place object in v1.1** | **Place object with v2**

https://api.x.com/2/tweets?ids=1370161532013735937&expansions=geo.place\_id&tweet.fields=geo&place.fields=contained\_within,country,country\_code,full\_name,geo,id,name,place_type | -| "place": \{
"id": "f7eb2fa2fea288b1",
"url": "https:\\/\\/api.x.com\\/1.1\\/geo\\/id\\/f7eb2fa2fea288b1.json",
"place_type": "city",
"name": "Lakewood",
"full_name": "Lakewood, CO",
"country_code": "US",
"country": "United States",
"contained_within": \[\],
"bounding_box": \{
"type": "Polygon",
"coordinates": \[
\[
\[
-105.193475,
39.60973
\],
\[
-105.053164,
39.60973
\],
\[
-105.053164,
39.761974
\],
\[
-105.193475,
39.761974
\]
\]
\]
},
"attributes": {}
} | \{
"data": \[\{
"id": "1370161532013735937",
"text": "Another #test with a video and @TwitterDev mention. Excited for new format migration docs! https://t.co/XVLZ3uwikc https://t.co/dz4oByygWA",
"geo": \{
"place_id": "f7eb2fa2fea288b1"
}
}\],
"includes": \{
"places": \[\{
"name": "Lakewood",
"place_type": "city",
"full_name": "Lakewood, CO",
"id": "f7eb2fa2fea288b1",
"geo": \{
"type": "Feature",
"bbox": \[
-105.193475,
39.60973,
-105.053164,
39.761974
\],
"properties": {}
},
"country_code": "US",
"country": "United States"
}\]
} | - -**Next step** - -* Learn more about [fields](/x-api/fundamentals/fields) -* Learn more about [expansions](/x-api/fundamentals/expansions) -* Learn how to [use fields with expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) - - -### Migrating from Native Enriched data format to v2 - -The Native Enriched data format is used by our [enterprise](/x-api/enterprise-gnip-2.0/enterprise-gnip) products. - -The Native Enriched data format has been updated to provide edited Tweet metadata. To learn more about Edit Tweet metadata, check out the [Edit Tweets fundamentals](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) page. - -If you are using the standard v1.1 endpoints, please refer to the [standard v1.1 to v2 guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2). If you are using the enterprise products with Activity Streams, we have an [Activity Streams to v2](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) guide for you as well. - -X API v2 introduces new JSON designs for [Tweet](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the Native Enriched format returns Tweet objects in a results array, while X API v2 returns a data array.  -* Instead of using both favorites (in Tweet object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Tweet and user attributes are only included if they have non-null values.  -* All id fields in v2 will be in string format -   - -In addition to the changes made to the new JSON format, we also introduced a new set of fields to the Tweet object including the following: - -* conversation_id -* reply_settings -* alt_text on media -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields -* Several new [polls](/x-api/fundamentals/data-dictionary#poll) fields -   - -Many legacy and deprecated fields are being removed: - -* contributors -* Certain entities.media and extended_entities.media fields -* filter_level -* timestamp_ms -* truncated - -#### Native Enriched vs v2 payload structure - -The following table displays the high-level objects and format that you can expect to receive from v2 compared to the Native Enriched format. - -| | **Native Enriched structure** | **v2 structure** | -| :--- | :--- | :--- | -| **Default** | \{
~tweet object fields~,

"user": {},
"place": {},
"entities": \{
"hashtags": \[\],
"urls": \[\],
"user_mentions": \[\],
"symbols": \[\],
"annotations": \[\],
"media": \[\]
},
"extended_entities": {},
"matching_rules": \[\]
} | \{
"data": \[\{
"id",
"text",

"edit\_history\_tweet_ids"
}\]
} | -| **With defined [field and expansion](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) parameters** | | \{
"data": \[\{
~tweet object fields~,
"entities": \{
"hashtags": \[\],
"cashtags": \[\],
"mentions": \[\],
"urls": \[\],
},
"attachments": \{
"media_keys": \[\],
"poll_ids": \[\]
}
}\],
"includes": \[
"tweets": \[~user objects~\],
"users": \[~user objects~\],
"media": \[~media objects~\],
"places": \[~place object~\],
"polls": \[~poll object~\]
\],
"matching_rules": \[\]
} | - -**Field mapping** - -The following section describes which native enriched fields map to v2 fields, as well as which v2 parameters are required to receive the new field. -  - -#### Tweet object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| created_at | data.created_at | tweet.fields=created_at | String | -| id | | N/A - See id | | -| id_str | data.id | Default | String | -| text | data.text | Default | String | -| edit_history | data.edit\_history\_tweet_ids | Default | Array | -| edit_controls | data.edit_controls | tweet.fields=edit_controls | Object | -| editable | data.edit\_controls.is\_edit_eligible | tweet.fields=edit_controls | Boolean | -| display\_text\_range | | N/A - text includes complete text | | -| source | data.source | tweet.fields=source | String | -| truncated | | N/A - text includes complete text | | -| Not available | data.conversation_id | tweet.fields=conversation_id | String | -| Not available | data.reply_settings | tweet.fields=reply_settings | String | -| in\_reply\_to\_status\_id | | N/A - See referenced_tweets.id | | -| in\_reply\_to\_status\_id_str | data.referenced_tweets.id (if type=replied_to) | expansions=referenced_tweets.id | String | -| in\_reply\_to\_user\_id | | N/A - See in\_reply\_to\_user\_id_str | | -| in\_reply\_to\_user\_id_str | data.in\_reply\_to\_user\_id | tweet.fields=in\_reply\_to\_user\_id | String | -| in\_reply\_to\_screen\_name | includes.users..username | tweet.fields=in\_reply\_to\_user\_id&expansions=entities.mentions.username | String | -| user | includes.users | expansions=author_id | Object | -| user.id_str | data.author_id | tweet.fields=author_id | String | -| geo | data.geo.place_id | tweet.fields=geo | | -| coordinates | data.geo.place_id | tweet.fields=geo | | -| place | data.geo.place_id | tweet.fields=geo | | -| is\_quoted\_status | data.referenced_tweets.id (if type=quoted) | tweet.fields=referenced_tweets | String | -| extended\_tweet.full\_text | | N/A - text is complete text | | -| Not available | data.public_metrics | tweet.fields=public_metrics | Object | -| quote_count | data.public\_metrics.quote\_count | tweet.fields=public_metrics | Int | -| reply_count | data.public\_metrics.reply\_count | tweet.fields=public_metrics | Int | -| retweet_count | data.public\_metrics.retweet\_count | tweet.fields=public_metrics | Int | -| favorite_count | data.public\_metrics.like\_count | tweet.fields=public_metrics | Int | -| Not available | data.non\_public\_metrics | tweet.fields=non\_public\_metrics | Object | -| Not available | data.non\_public\_metrics.impression_count | tweet.fields=non\_public\_metrics | Int | -| Not available | data.non\_public\_metrics.url\_link\_count | tweet.fields=non\_public\_metrics | Int | -| Not available | data.non\_public\_metrics.user\_profile\_count | tweet.fields=non\_public\_metrics | Int | -| Not available | data.organic_metrics | tweet.fields=organic_metrics | Object | -| Not available | data.organic\_metrics.like\_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.retweet\_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.reply\_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.impression\_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.url\_link_count | tweet.fields=organic_metrics | Int | -| Not available | data.organic\_metrics.user\_profile_count | tweet.fields=organic_metrics | Int | -| Not available | data.promoted_metrics | tweet.fields=promoted_metrics | Object | -| Not available | data.promoted\_metrics.like\_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.retweet\_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.reply\_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.impression\_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.url\_link_count | tweet.fields=promoted_metrics | Int | -| Not available | data.promoted\_metrics.user\_profile_count | tweet.fields=promoted_metrics | Int | -| contributors | Not available | Not available | | -| entities | data.entities | tweet.fields=entities | Object | -| entities.user_mentions | data.entities.mentions | tweet.fields=entities | Array of objects | -| entities.symbols | data.entities.cashtags | tweet.fields=entities | Array of objects | -| entities.hashtags | data.entities.hashtags | tweet.fields=entities | Array of objects | -| entities.urls | data.entities.urls | tweet.fields=entities | Array of objects | -| entities.media | includes.media | expansions=attachments.media_keys | Array of objects | -| entities.annotations | | tweet.fields=entities,context_annotations | Object | -| entities.annotations.context | data.context_annotations | tweet.fields=entities,context_annotations | Array of objects | -| No equivalent | data.context_annotations.domain | tweet.fields=context_annotations | Object | -| entities.annotations.context.context\_domain\_id_str | data.context_annotations.domain.id | tweet.fields=context_annotations | String | -| entities.annotations.context.context\_domain\_id | Not available | Not available - see data.context_annotations.domain.id for string format | | -| entities.annotations.context.context\_domain\_name | data.context_annotations.domain.name | tweet.fields=context_annotations | String | -| entities.annotations.context.context\_domain\_description | data.context_annotations.domain.description | tweet.fields=context_annotations | String | -| No equivalent | data.context_annotations.entity | tweet.fields=context_annotations | Object | -| entities.annotations.context.context\_entity\_id_str | data.context_annotations.entity.id | tweet.fields=context_annotations | String | -| entities.annotations.context.context\_entity\_id | Not available | Not available - see data.context_annotations.entity.id for string format | | -| entities.annotations.context.context\_entity\_name | data.context_annotations.entity.name | tweet.fields=context_annotations | String | -| entities.annotations.context.context\_entity\_description | data.context_annotations.entity.description | tweet.fields=context_annotations | String | -| entities.annotations.entity | data.entities.annotations | tweet.fields=entities,context_annotations | Array of objects | -| extended_entities | data.attachments | tweet_fields=attachments | Object | -| favorited | Not available | Not available | | -| retweeted | Not available | Not available | | -| retweeted_status | | | | -| possibly_sensitive | data.possibly_sensitive | tweet.fields=possibly_sensitive | Boolean | -| lang | data.lang | tweet.fields=lang | String | -| filter_level | Not available | Not available | | -| scopes | Not available | Not available | | -| timestamp_ms | Not available | Not available | | -| withheld | data.withheld | tweet.fields=withheld | Array of objects | -| matching_rules | matching_rules | | Array of objects | -| matching_rules.id | Not available | Not available | | -| matching\_rules.id\_str | matching_rules.id | Default with filtered stream | String | -| matching_rules.tag | matching_rules.tag | Default with filtered stream | String | - -#### User object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| user | includes.users | expansions=author_id | Array of objects | -| user.id | Not available | N/A - See includes.users.id | String | -| user.id_str | includes.users.id | expansions=author_id | String | -| user.name | includes.users.name | expansions=author_id | String | -| user.screen_name | includes.user.username | expansions=author_id | String | -| user.location | includes.users.location | expansions=author_id&user.fields=location | Object | -| user.description | includes.users.description | expansions=author_id&user.fields=description | String | -| Not available | includes.users.url | expansions=author_id&user.fields=url | String | -| user.followers_count | includes.users.public\_metrics.followers\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| user.friends_count | includes.users.public\_metrics.following\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| user.listed_count | includes.users.public\_metrics.listed\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| user.created_at | includes.users.created_at | expansions=author\_id&user.fields=created\_at | String | -| user.favourites_count | | Not yet available | | -| user.verified | includes.users.verified | expansions=author_id&user.fields=verified | Boolean | -| Not available | includes.users.pinned\_tweet\_id | expansions=author\_id&user.fields=pinned\_tweet_id | String | -| user.statuses_count | includes.users.public\_metrics.tweet\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| user.profile\_image\_url_https | includes.users.profile\_image\_url | expansions=author\_id&user.fields=profile\_image_url | String | -| user.translator_type | Not available | Not available | | -| user.utc_offset | Not available | Not available | | -| user.time_zone | Not available | Not available | | -| user.geo_enabled | Not available | Not available | | -| user.lang | Not available | Not available - infer from Tweet lang | | -| user.contributors_enabled | Not available | Not available | | -| user.is_translator | Not available | Not available | | -| user.profile\_background\_color | Not available | Not available | | -| user.profile\_background\_image_url | Not available | Not available | | -| user.profile\_background\_image\_url\_https | Not available | Not available | | -| user.profile\_background\_title | Not available | Not available | | -| user.profile\_sidebar\_border_color | Not available | Not available | | -| user.profile\_sidebar\_fill_color | Not available | Not available | | -| user.profile\_text\_color | Not available | Not available | | -| user.profile\_user\_background_image | Not available | Not available | | -| user.profile\_image\_url | | See includes.user.profile\_image\_url | | -| user.default_profile | Not available | Not available | | -| user.default\_profile\_image | Not available | Not available | | -| user.following | Not available | Not available | | -| user.follow\_request\_sent | Not available | Not available | | -| user.notifications | Not available | Not available | | -| user.withheld\_in\_countries | includes.users.withheld | expansions=author_id&user.fields=withheld | Object | -| user.protected | includes.users.protected | expansions=author_id&user.fields=protected | Boolean | -| Not available | includes.users.entities | expansions=author_id&user.fields=entities | Object | -| Not available | includes.users.entities.url | expansions=author_id&user.fields=entities | Object | -| Not available | includes.users.entities.url.urls | expansions=author_id&user.fields=entities | Array of objects | -| Not available | includes.users.entities.url.urls.start | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.url.urls.end | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.url.urls.url | expansions=author_id&user.fields=entities | String | -| user.url | includes.users.entities.url.urls.expanded_url | expansions=author_id&user.fields=entities | String | -| Not available | includes.users.entities.url.urls.display_url | expansions=author_id&user.fields=entities | String | -| Not available | includes.users.entities.descriptions | expansions=author_id&user.fields=entities | Object | -| Not available | includes.users.entities.descriptions.hashtags | expansions=author_id&user.fields=entities | Array of objects | -| Not available | includes.users.entities.descriptions.hashtags.start | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.descriptions.hashtags.end | expansions=author_id&user.fields=entities | Int | -| included in user.description | includes.users.entities.descriptions.hashtags.tag | expansions=author_id&user.fields=entities | String | -| Not available | includes.users.entities.descriptions.mentions | expansions=author_id&user.fields=entities | Array of objects | -| Not available | includes.users.entities.descriptions.mentions.start | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.descriptions.mentions.end | expansions=author_id&user.fields=entities | Int | -| Included in user.description | includes.users.entities.descriptions.mentions.username | expansions=author_id&user.fields=entities | String | -| Not available | includes.users.entities.descriptions.cashtags | expansions=author_id&user.fields=entities | Array of objects | -| Not available | includes.users.entities.descriptions.cashtags.start | expansions=author_id&user.fields=entities | Int | -| Not available | includes.users.entities.descriptions.cashtags.end | expansions=author_id&user.fields=entities | Int | -| Included in user.description | includes.users.entities.descriptions.cashtags.tag | expansions=author_id&user.fields=entities | String | - -#### Entities and expanded entities objects - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| entities | data.entities | tweet.fields=entities | Object | -| entities.hashtags | data.entities.hashtags | tweet.fields=entities | Array of objects | -| entities.hashtags.indices\[0\] | data.entities.hashtags.start | tweet.fields=entities | Integer | -| entities.hashtags.indices\[1\] | data.entities.hashtags.end | tweet.fields=entities | Integer | -| entities.hashtags.text | data.entities.hashtags.tag | tweet.fields=entities | String | -| entities.urls | data.entities.urls | tweet.fields=entities | Array of objects | -| entities.urls.indices\[0\] | data.entities.urls.start | tweet.fields=entities | Integer | -| entities.urls.indices\[1\] | data.entities.urls.end | tweet.fields=entities | Integer | -| entities.urls.url | data.entities.urls.url | tweet.fields=entities | String | -| entities.urls.expanded_url | data.entities.urls.expanded_url | tweet.fields=entities | String | -| entities.urls.display_url | data.entities.urls.display_url | tweet.fields=entities | String | -| entities.urls.unwound.url | data.entities.urls.unwound_url | tweet.fields=entities | String | -| entities.urls.unwound.status | data.entities.urls.status | tweet.fields=entities | String | -| entities.urls.unwound.title | data.entities.urls.title | tweet.fields=entities | String | -| entities.urls.unwound.description | data.entities.urls.description | tweet.fields=entities | String | -| Not available | data.entities.urls.images | tweet.fields=entities | Array of objects | -| Not available | data.entities.urls.images.url | tweet.fields=entities | String | -| Not available | data.entities.urls.images.width | tweet.fields=entities | Int | -| Not available | data.entities.urls.images.height | tweet.fields=entities | Int | -| entities.user_mentions | data.entities.mentions | tweet.fields=entities | Array of objects | -| entities.user_mentions.indicies\[0\] | data.entities.mentions.start | tweet.fields=entities | Integer | -| entities.user_mentions.indicies\[1\] | data.entities.mentions.end | tweet.fields=entities | Integer | -| entities.user\_mentions.screen\_name | data.entities.mentions.username | tweet.fields=entities | String | -| entities.symbols | data.entities.cashtags | tweet.fields=entities | Array of objects | -| entities.symbols.indices\[0\] | data.entities.cashtags.start | tweet.fields=entities | Integer | -| entities.symbols.indices\[1\] | data.entities.cashtags.end | tweet.fields=entities | Integer | -| entities.symbols.text | data.entities.cashtags.tag | tweet.fields=entities | String | -| entities.media OR extended_entities.media | includes.media | expansions=attachments.media_keys | Array of objects | -| entities.media.id_str OR extended\_entities.media.id\_str | includes.media.media_key | expansions=attachments.media_keys | String | -| entities.media.id OR extended_entities.media.id | | Not available - id is a String | | -| entities.media.type OR extended_entities.media.type | includes.media.media.type | expansions=attachments.media_keys | String | -| entities.media.indices OR extended_entities.media.indices | Not available | Not available | | -| Not available | includes.media.alt_text | expansions=attachments.media\_keys&media.fields=alt\_text | String | -| entities.media.additional\_media\_info OR extended\_entities.media.additional\_media_info | Not available | Not available | | -| entities.media.additional\_media\_info.monetizable OR extended\_entities.media.additional\_media_info.monetizable | Not available | Not available | | -| entities.media.media_url OR extended\_entities.media.media\_url | | N/A - See includes.media.url | String | -| entities.media.media\_url\_https OR extended\_entities.media.media\_url_https | includes.media.url | expansions=attachments.media_keys&media.fields=url | String | -| entities.media.url OR extended_entities.media.url | | | | -| entities.media.display_url OR extended\_entities.media.expanded\_url | | | | -| entities.media.expanded_url | | | | -| entities.media.media\_url\_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | String | -| extended_entities | data.attachments | tweet_fields=attachments | Object | -| extended_entities | data.attachments.media_keys | tweet.fields=attachments | Array of objects | -| Not available | data.attachments.poll_ids | tweet.fields=attachments | Array of objects | -| extended_entities.media.sizes.thumb.w | | Not Available | | -| extended_entities.media.sizes.thumb.h | | Not Available | | -| extended_entities.media.sizes.thumb.resize | | Not Available | | -| extended_entities.media.sizes.large.w | includes.media.height | expansions=attachments.media_keys&media.fields=height | | -| extended_entities.media.sizes.large.h | includes.media.width | expansions=attachments.media_keys&media.fields=width | | -| extended_entities.media.sizes.large.resize | Not Available | Not Available | | -| extended_entities.media.sizes.small.w | Not Available | Not Available | | -| extended_entities.media.sizes.small.h | Not Available | Not Available | | -| extended_entities.media.sizes.small.resize | Not Available | Not Available | | -| extended_entities.media.sizes.medium.w | Not Available | Not Available | | -| extended_entities.media.sizes.medium.h | Not Available | Not Available | | -| extended_entities.media.sizes.medium.resize | Not Available | Not Available | | -| extended\_entities.media.media\_url_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | String | -| extended\_entities.media.video\_info.aspect_ratio | Not available | Not available | | -| extended_entities.media.variants | Not available | Not available | | -| extended_entities.media.variants.bitrate | Not available | Not available | | -| extended\_entities.media.variants.content\_type | Not available | Not available | | -| extended_entities.media.variants.url | Not available | Not available | | -| extended\_entities.media.video\_info.duration_millis | includes.media.duration_ms | expansions=attachments.media\_keys&media.fields=duration\_ms | Int | -| Not available | includes.media.public_metrics | expansions=attachments.media\_keys&media.fields=public\_metrics | Object | -| Not available | includes.media.public\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=public\_metrics | Int | -| Not available | includes.media.non\_public\_metrics | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Object | -| Not available | includes.media.non\_public\_metrics.playback\_0\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_25\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_50\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_75\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_100\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.organic_metrics | expansions=attachments.media\_keys&media.fields=organic\_metrics | Object | -| Not available | includes.media.organic\_metrics.playback\_0_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_25_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_50_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_75_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_100_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.promoted_metric | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Object | -| Not available | includes.media.promoted\_metric.playback\_0_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metric.playback\_25_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metric.playback\_50_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metric.playback\_75_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metric.playback\_100_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | - -#### Place object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| place | includes.places | expansions=geo.place_id | Array of objects | -| place.id | includes.places.id | expansions=geo.place_id | String | -| place.url | Not available | Not available | | -| place.id.place_type | includes.places.place_type | expansions=geo.place\_id&place.fields=place\_type | String | -| place.id.name | includes.places.name | expansions=geo.place_id&place.fields=name | String | -| place.id.full_name | includes.places.full_name | expansions=geo.place_id | String | -| place.id.country_code | includes.places.country_code | expansions=geo.place\_id&place.fields=country\_code | String | -| place.id.country | includes.places.country | expansions=geo.place_id&place.fields=country | String | -| place.id.contained_within | includes.places.contained_within | expansions=geo.place\_id&place.fields=contained\_within | Array | -| place.id.bounding_box.type | includes.places.geo.type | expansions=geo.place\_id&place.fields=place\_type | String | -| place.id.bounding_box.coordinates | includes.places.geo.bbox | expansions=geo.place_id&place.fields=geo | Array | -| place.id.attributes | includes.places.properties | expansions=geo.place_id&place.fields=geo | Object | - -#### Poll object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Native Enriched format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| entities.polls | includes.polls | expansions=attachments.poll_ids | Array of objects | -| Not available | includes.polls.id | expansions=attachments.poll_ids | String | -| entities.poll.options | includes.polls.options | expansions=attachments.poll_ids | Array of objects | -| entities.polls.options.position | includes.polls.options.position | expansions=attachments.poll_ids | Int | -| entities.polls.options.text | includes.polls.options.label | expansions=attachments.poll_ids | String | -| Not available | includes.polls.options.votes | expansions=attachments.poll_ids | Int | -| Not available | includes.polls.voting_status | expansions=attachments.poll\_ids&poll.fields=voting\_status | String | -| entities.polls.duration_minutes | includes.polls.duration_minutes | expansions=attachments.poll\_ids&poll.fields=duration\_minutes | Int | -| entities.polls.end_datetime | includes.polls.end_datetime | expansions=attachments.poll\_ids&poll.fields=end\_datetime | Date (ISO 8601) | - - -### Migrating from Activity Streams data format to v2 - -The Activity Streams data format is available with our [enterprise](/x-api/enterprise-gnip-2.0/enterprise-gnip) products. - -The Activity Streams data format has been updated to provide edited Tweet metadata. To learn more about Edit Tweet metadata, check out the [Edit Tweets fundamentals](/x-api/enterprise-gnip-2.0/fundamentals/edit-tweets) page. - -If you are using the standard v1.1 endpoints, please refer to the [standard v1.1 to v2 guide](/x-api/migrate/overview). If you are using the premium endpoints, or the Native Enriched format for enterprise, please refer to the [Native Enriched to v2 guide](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2). - -X API v2 introduces new JSON designs for [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the Activity Streams format returns Tweet objects in a results array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "activities", X API v2 JSON refers to Retweeted and Quoted Tweets.  -* Instead of using both favorites (in Tweet object) and favourites (in user object), X API v2 uses the term like.  -* Twitter is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Tweet and user attributes are only included if they have non-null values.  -* All id fields in v2 will be in string format. -   - -In addition to the changes made to the new JSON format, we also introduced a new set of fields to the Tweet object including the following: - -* conversation_id -* reply_settings -* alt_text on media -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields -* Several new [polls](/x-api/fundamentals/data-dictionary#poll) fields -   - -Many legacy and deprecated fields are being removed or replaced: - -* display\_text\_range -* generator -* gnip -* link -* objectType -* provider -* twitter_entities.symbols replaced with data.entities.cashtags -* Certain twitter\_extended\_entities.media and twitter_entities.media fields -* twitter\_filter\_level -* twitterTimeZone -* verb - -#### Tweet object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| postedTime | data.created_at | tweet.fields=created_at | Date (ISO 8601) | -| generator | Not Available | Not Available | | -| generator.link | Not Available | Not Available | | -| generator.displayName | data.source | tweet.fields=source | String | -| twitter_lang | data.lang | tweet.fields=lang | String | -| Not Available | data.conversation_id | tweet.fields=conversation_id | String | -| Not Available | data.reply_settings | tweet.fields=reply_settings | String | -| Not Available | data.possibly_sensitive | tweet.fields=possibly_sensitive | Boolean | -| Not Available | data.withheld | tweet.fields=withheld | Object | -| objectType | Not Available | Not Available | | -| verb | Not Available | Not Available | | -| provider | Not Available | Not Available | | -| provider.objectType | Not Available | Not Available | | -| provider.displayName | Not Available | Not Available | | -| provider.link | Not Available | Not Available | | -| link | Not Available | Not Available | | -| display\_text\_range | Not Available | Not Available | | -| object | Not Available | Not Available | | -| object.objectType | Not Available | Not Available | | -| object.id | Not Available | Not Available | | -| object.summary | data.text | default | String | -| object.edit_history | data.edit\_history\_tweet_ids | default | Array | -| object.edit_controls | data.edit_controls | tweet.fields=edit_controls | Object | -| object.editable | data.edit\_controls.is\_edit_eligible | tweet.fields=edit_controls | Boolean | -| object.link | Not Available | Not Available | | -| object.postedTime | data.created_at | tweet.fields=created_at | Date (ISO 8601) | -| Derived from actor.id | data.author_id | tweet.fields=created_at | | -| twitter\_filter\_level | Not Available | Not Available | | -| Derived from username in inReplyTo.link | data.in\_reply\_to\_user\_id | tweet.fields=in\_reply\_to\_user\_id | String | -| Not Available | data.referenced_tweets | tweet.fields=referenced_tweets | Array of objects | -| Not Available | data.referenced_tweets.type | tweet.fields=referenced_tweets | String | -| Derived from inReplyTo.link | data.referenced_tweets.id | tweet.fields=referenced_tweets | String | -| Not Available | data.attachments | tweet.fields=attachments | Object | -| Derived from twitter\_entities.media.id\_str | data.attachments.media_keys | tweet.fields=attachments | Array | -| Not Available | data.attachments.poll_ids | tweet.fields=attachments | Array | -| twitter_entities | data.entities | tweet.fields=entities | Object | -| Not Available | data.entities.annotations | tweet.fields=entities | Array of objects | -| Not Available | data.entities.annotations.start | tweet.fields=entities | Int | -| Not Available | data.entities.annotations.end | tweet.fields=entities | Int | -| Not Available | data.entities.annotations.probability | tweet.fields=entities | Float | -| Not Available | data.entities.annotations.type | tweet.fields=entities | String | -| Not Available | data.entities.annotations.normalized_text | tweet.fields=entities | String | -| twitter_entities.urls | data.entities.urls | tweet.fields=entities | Array of objects | -| twitter_entities.urls.indices\[0\] | data.entities.urls.start | tweet.fields=entities | Int | -| twitter_entities.urls.indices\[1\] | data.entities.urls.end | tweet.fields=entities | Int | -| twitter_entities.urls.url | data.entities.urls.url | tweet.fields=entities | String | -| twitter\_entities.urls.expanded\_url | data.entities.urls.expanded_url | tweet.fields=entities | String | -| twitter\_entities.urls.display\_url | data.entities.urls.display_url | tweet.fields=entities | String | -| Not Available | data.entities.urls.images | tweet.fields=entities | Array of objects | -| Not Available | data.entities.urls.images.url | tweet.fields=entities | String | -| Not Available | data.entities.urls.images.width | tweet.fields=entities | Int | -| Not Available | data.entities.urls.images.height | tweet.fields=entities | Int | -| gnip.urls.expanded_status | data.entities.urls.status | tweet.fields=entities | Int | -| gnip.urls.expanded\_url\_title | data.entities.urls.title | tweet.fields=entities | String | -| gnip.urls.expanded\_url\_description | data.entities.urls.description | tweet.fields=entities | String | -| gnip.urls.expanded_url | data.entities.urls.unwound_url | tweet.fields=entities | String | -| twitter_entities.symbols | data.entities.cashtags | tweet.fields=entities | Array of objects | -| twitter_entities.symbols.indices\[0\] | data.entities.cashtags.start | tweet.fields=entities | Int | -| twitter_entities.symbols.indices\[1\] | data.entities.cashtags.end | tweet.fields=entities | Int | -| twitter_entities.symbols.text | data.entities.cashtags.tag | tweet.fields=entities | String | -| twitter_entities.hashtags | data.entities.hashtags | tweet.fields=entities | Array of objects | -| twitter_entities.hashtags.indices\[0\] | data.entities.hashtags.start | tweet.fields=entities | Int | -| twitter_entities.hashtags.indices\[1\] | data.entities.hashtags.end | tweet.fields=entities | Int | -| twitter_entities.hashtags.text | data.entities.hashtags.tag | tweet.fields=entities | String | -| twitter\_entities.user\_mentions | data.entities.mentions | tweet.fields=entities | Array of objects | -| twitter\_entities.user\_mentions.indices\[0\] | data.entities.mentions.start | tweet.fields=entities | Int | -| twitter\_entities.user\_mentions.indices\[1\] | data.entities.mentions.end | tweet.fields=entities | Int | -| twitter\_entities.user\_mentions.screen_name | data.entities.mentions.tag | tweet.fields=entities | String | -| twitter\_entities.user\_mentions.id_str | data.entities.mentions.id | tweet.fields=entities | String | -| twitter\_entities.user\_mentions.id | Not Available | Not Available | | -| Not Available | data.context_annotations | tweet.fields=context_annotations | Array of objects | -| Not Available | data.context_annotations.domain | tweet.fields=context_annotations | Object | -| Not Available | data.context_annotations.domain.id | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.domain.name | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.domain.description | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.entity | tweet.fields=context_annotations | Object | -| Not Available | data.context_annotations.entity.id | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.entity.name | tweet.fields=context_annotations | String | -| Not Available | data.context_annotations.entity.description | tweet.fields=context_annotations | String | -| geo | data.geo | tweet.fields=geo | Object | -| Derived from location.link | data.geo.place_id | tweet.fields=geo | String | -| Not Available | data.public_metrics | tweet.fields=public_metrics | Object | -| favoritesCount | data.public\_metrics.like\_count | tweet.fields=public_metrics | Int | -| retweetCount | data.public\_metrics.retweet\_count | tweet.fields=public_metrics | Int | -| Not Available | data.public\_metrics.quote\_count | tweet.fields=public_metrics | Int | -| Not Available | data.public\_metrics.reply\_count | tweet.fields=public_metrics | Int | -| Not Available | data.non\_non\_public_metrics | tweet.fields=non\_public\_metrics | Object | -| Not Available | data.non\_public\_metrics.impression_count | tweet.fields=non\_public\_metrics | Int | -| Not Available | data.non\_public\_metrics.url\_link\_count | tweet.fields=non\_public\_metrics | Int | -| Not Available | data.non\_public\_metrics.user\_profile\_count | tweet.fields=non\_public\_metrics | Int | -| Not Available | data.organic_metrics | tweet.fields=organic_metrics | Object | -| Not Available | data.organic\_metrics.like\_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.retweet\_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.reply\_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.impression\_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.url\_link_count | tweet.fields=organic_metrics | Int | -| Not Available | data.organic\_metrics.user\_profile_count | tweet.fields=organic_metrics | Int | -| Not Available | data.promoted_metrics | tweet.fields=promoted_metrics | Object | -| Not Available | data.promoted\_metrics.like\_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.retweet\_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.reply\_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.impression\_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.url\_link_count | tweet.fields=promoted_metrics | Int | -| Not Available | data.promoted\_metrics.user\_profile_count | tweet.fields=promoted_metrics | Int | -| gnip.profileLocations | Not Available | Not Available | | -| gnip.profileLocations.address | Not Available | Not Available | | -| gnip.profileLocations.address.country | Not Available | Not Available | | -| gnip.profileLocations.address.countryCode | Not Available | Not Available | | -| gnip.profileLocations.displayName | Not Available | Not Available | | -| gnip.profileLocations.geo | Not Available | Not Available | | -| gnip.profileLocations.geo.coordinates | Not Available | Not Available | | -| gnip.profileLocations.geo.type | Not Available | Not Available | | -| gnip.profileLocations.objectType | Not Available | Not Available | | - -#### User object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| actor | includes.users | expansions=author_id | Array of objects | -| Derived from actor.id | includes.users.id | expansions=author_id | String | -| actor.displayName | includes.users.name | expansions=author_id | String | -| actor.preferredUsername | includes.users.username | expansions=author_id | String | -| actor.postedTime | includes.users.created_at | expansions=author\_id&user.fields=created\_at | Date (ISO 8601) | -| actor.summary | includes.users.description | expansions=author_id&user.fields=description | String | -| Not Available | includes.users.pinned\_tweet\_id | expansions=author\_id&user.fields=pinned\_tweet_id | String | -| Not Available | includes.users.protected | expansions=author_id&user.fields=protected | Boolean | -| actor.link | Not Available | Not Available - construct from includes.users.username | | -| actor.twitterTimeZone | Not Available | Not Available - infer from Tweet created_at | | -| actor.utcOffset | Not Available | Not Available - infer from Tweet created_at | | -| actor.favoritesCount | Not Available | Not Available | | -| actor.followersCount | includes.users.public\_metrics.followers\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| actor.friendsCount | includes.users.public\_metrics.following\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| actor.listedCount | includes.users.public\_metrics.listed\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| actor.statusesCount | includes.users.public\_metrics.tweet\_count | expansions=author\_id&user.fields=public\_metrics | Int | -| actor.languages\[\] | Not Available | Not Available -  infer from Tweet  lang | | -| actor.location.displayName | includes.users.location | expansions=author_id&user.fields=location | String | -| actor.image | includes.users.profile\_image\_url | expansions=author\_id&user.fields=profile\_image_url | String | -| actor.links | includes.users.url | expansions=author_id&user.fields=url | String | -| actor.verified | includes.users.verified | expansions=author_id&user.fields=verified | Boolean | -| Not Available | includes.users.withheld | expansions=author_id&user.fields=withheld | Object | -| Not Available | includes.users.entities | expansions=author_id&user.fields=entities | Object | -| Not Available | includes.users.entities.url | expansions=author_id&user.fields=entities | Object | -| actor.links | includes.users.entities.url.urls | expansions=author_id&user.fields=entities | Array of objects | -| Not Available | includes.users.entities.url.urls.start | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.url.urls.end | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.url.urls.url | expansions=author_id&user.fields=entities | String | -| actor.links.href | includes.users.entities.url.urls.expanded_url | expansions=author_id&user.fields=entities | String | -| Not Available | includes.users.entities.url.urls.display_url | expansions=author_id&user.fields=entities | String | -| Not Available | includes.users.entities.description | expansions=author_id&user.fields=entities | Object | -| Not Available | includes.users.entities.description.hashtags | expansions=author_id&user.fields=entities | Array of objects | -| Not Available | includes.users.entities.description.hashtags.start | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.hashtags.end | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.hashtags.tag | expansions=author_id&user.fields=entities | String | -| Not Available | includes.users.entities.description.mentions | expansions=author_id&user.fields=entities | Array of objects | -| Not Available | includes.users.entities.description.mentions.start | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.mentions.end | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.mentions.username | expansions=author_id&user.fields=entities | String | -| Not Available | includes.users.entities.description.cashtags | expansions=author_id&user.fields=entities | Array of objects | -| Not Available | includes.users.entities.description.cashtags.start | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.cashtags.end | expansions=author_id&user.fields=entities | Int | -| Not Available | includes.users.entities.description.cashtags.tag | expansions=author_id&user.fields=entities | String | - - -#### Poll object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| Not Available | includes.polls | expansions=attachments.poll_ids | Array of objects | -| Not Available | includes.polls.id | expansions=attachments.poll_ids | String | -| Not Available | includes.polls.options | expansions=attachments.poll_ids | Array of objects | -| Not Available | includes.polls.options.position | expansions=attachments.poll_ids | Int | -| Not Available | includes.polls.options.label | expansions=attachments.poll_ids | String | -| Not Available | includes.polls.options.votes | expansions=attachments.poll_ids | Int | -| Not Available | includes.polls.voting_status | expansions=attachments.poll\_ids&poll.fields=voting\_status | String | -| Not Available | includes.polls.duration_minutes | expansions=attachments.poll\_ids&poll.fields=duration\_minutes | Int | -| Not Available | includes.polls.end_datetime | expansions=attachments.poll\_ids&poll.fields=end\_datetime | Date (ISO 8601) | - -#### Place object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| location | includes.places | expansions=geo.place_id | array of objects | -| location.displayName | includes.places.full_name | expansions=geo.place_id | string | -| Parsed from location.link | includes.places.id | expansions=geo.place_id | string | -| location.name | includes.places.name | expansions=geo.place_id&place.fields=name | string | -| location.country_code | includes.places.country | expansions=geo.place_id&place.fields=country | string | -| location.twitter\_place\_type | includes.places.place_type | expansions=geo.place\_id&place.fields=place\_type | string | -| location.twitter\_country\_code | includes.places.country_code | expansions=geo.place\_id&place.fields=country\_code | string | -| location.geo | includes.places.geo | expansions=geo.place_id&place.fields=geo | object | -| location.geo.type | includes.places.geo.type | expansions=geo.place_id&place.fields=geo | string | -| location.geo.coordinates | includes.places.geo.bbox | expansions=geo.place_id&place.fields=geo | array | -| Not Available | includes.places.geo.properties | expansions=geo.place_id&place.fields=geo | object | - -#### Media object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| twitter_entities.media OR twitter\_extended\_entities.media | includes.media | expansions=attachments.media_keys | Array of objects | -| twitter\_entities.media.id\_str OR twitter\_extended\_entities.media.id_str | includes.media.media_key | expansions=attachments.media_keys | String | -| twitter_entities.media.id OR twitter\_extended\_entities.media.id | Not available | Not available | | -| twitter_entities.media.indices OR twitter\_extended\_entities.media.indices | Not available | Not available | | -| twitter\_entities.media.additional\_media_info OR twitter\_extended\_entities.media.additional\_media\_info | Not available | Not available | | -| twitter\_entities.media.additional\_media_info.monetizable OR twitter\_extended\_entities.media.additional\_media\_info.monetizable | Not available | Not available | | -| twitter\_entities.media.media\_url OR twitter\_extended\_entities.media.media_url | Not available | Not available | | -| twitter\_entities.media.media\_url_https OR twitter\_extended\_entities.media.media\_url\_https | includes.media.preview\_image\_url | expansions=attachments.media\_keys&media.fields=preview\_image_url | String | -| twitter_entities.media.url OR twitter\_extended\_entities.media.url | Not available | Not available | | -| twitter\_entities.media.display\_url OR twitter\_extended\_entities.media.display_url | Not available | Not available | | -| twitter\_entities.media.expanded\_url OR twitter\_extended\_entities.media.expanded_url | Not available | Not available | | -| twitter_entities.media.type OR twitter\_extended\_entities.media.type | includes.media.type | expansions=attachments.media_keys | String | -| twitter_entities.media.sizes OR twitter\_extended\_entities.media.sizes | Not available | Not available | | -| twitter_entities.media.sizes.thumb OR twitter\_extended\_entities.media.sizes.thumb | Not available | Not available | | -| twitter_entities.media.sizes.thumb.h OR twitter\_extended\_entities.media.sizes.thumb.h | Not available | Not available | | -| twitter_entities.media.sizes.thumb.w OR twitter\_extended\_entities.media.sizes.thumb.w | Not available | Not available | | -| twitter_entities.media.sizes.thumb.resize OR twitter\_extended\_entities.media.sizes.thumb.resize | Not available | Not available | | -| twitter_entities.media.sizes.small OR twitter\_extended\_entities.media.sizes.small | Not available | Not available | | -| twitter_entities.media.sizes.small.h OR twitter\_extended\_entities.media.sizes.small.h | Not available | Not available | | -| twitter_entities.media.sizes.small.w OR twitter\_extended\_entities.media.sizes.small.w | Not available | Not available | | -| twitter_entities.media.sizes.small.resize OR twitter\_extended\_entities.media.sizes.small.resize | Not available | Not available | | -| twitter_entities.media.sizes.medium OR twitter\_extended\_entities.media.sizes.medium | Not available | Not available | | -| twitter_entities.media.sizes.medium.h OR twitter\_extended\_entities.media.sizes.medium.h | Not available | Not available | | -| twitter_entities.media.sizes.medium.w OR twitter\_extended\_entities.media.sizes.medium.w | Not available | Not available | | -| twitter_entities.media.sizes.medium.resize OR twitter\_extended\_entities.media.sizes.medium.resize | Not available | Not available | | -| twitter_entities.media.sizes.large OR twitter\_extended\_entities.media.sizes.large | Not available | Not available | | -| twitter_entities.media.sizes.large.h OR twitter\_extended\_entities.media.sizes.large.h | includes.media.height | expansions=attachments.media_keys&media.fields=height | Int | -| twitter_entities.media.sizes.large.w OR twitter\_extended\_entities.media.sizes.large.w | includes.media.width | expansions=attachments.media_keys&media.fields=width | Int | -| twitter_entities.media.sizes.large.resize OR twitter\_extended\_entities.media.sizes.large.resize | Not available | Not available | | -| twitter\_extended\_entities.media.video_info | Not available | Not available | | -| twitter\_extended\_entities.media.video\_info.aspect\_ratio | Not available | Not available | | -| twitter\_extended\_entities.media.video\_info.duration\_millis | includes.media.duration_ms | expansions=attachments.media\_keys&media.fields=duration\_ms | Int | -| twitter\_extended\_entities.media.video_info.variants | Not available | Not available | | -| twitter\_extended\_entities.media.video_info.variants.bitrate | Not available | Not available | | -| twitter\_extended\_entities.media.video\_info.variants.content\_type | Not available | Not available | | -| twitter\_extended\_entities.media.video_info.variants.url | Not available | Not available | | -| Not available | includes.media.alt_text | expansions=attachments.media\_keys&media.fields=alt\_text | String | -| Not available | includes.media.public_metrics | expansions=attachments.media\_keys&media.fields=public\_metrics | Object | -| Not available | includes.media.public\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=public\_metrics | Int | -| Not available | includes.media.non\_public\_metrics | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Object | -| Not available | includes.media.non\_public\_metrics.playback\_0\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_25\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_50\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_75\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.non\_public\_metrics.playback\_100\_count | expansions=attachments.media\_keys&media.fields=non\_public_metrics | Int | -| Not available | includes.media.organic_metrics | expansions=attachments.media\_keys&media.fields=organic\_metrics | Object | -| Not available | includes.media.organic\_metrics.playback\_0_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_25_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_50_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_75_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.playback\_100_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.organic\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=organic\_metrics | Int | -| Not available | includes.media.promoted_metrics | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Object | -| Not available | includes.media.promoted\_metrics.playback\_0_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.playback\_25_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.playback\_50_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.playback\_75_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.playback\_100_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | -| Not available | includes.media.promoted\_metrics.view\_count | expansions=attachments.media\_keys&media.fields=promoted\_metrics | Int | - -#### Matching rules object - -| | | | | -| :--- | :--- | :--- | :--- | -| **Activity Streams format** | **Twitter v2 format** | **Required v2 parameters** | **Type in v2** | -| gnip.matching_rules | matching_rules | Default in filtered stream | Array of objects | -| gnip.matching_rules.tag | matching_rules.tag | Default in filtered stream | String | -| gnip.matching_rules.tag.id | Not Available | Not Available | | -| gnip.matching\_rules.tag.id\_str | matching_rules.id | Default in filtered stream | String | - - -### Visual data format migration tool - -The visual data format migration tool is a web application that displays the fields that map from the [X API v1.1. data format](https://developer.x.com/en/docs/x-api/v1/data-dictionary/overview) to the [X API v2 format](/x-api/fundamentals/data-dictionary) for a given Tweet or user object. Either a Tweet ID or user ID can be provided to the application to see this mapping. - -Please note that you will need to log in with your Twitter account in order to use the app. -
- - +One of the biggest changes between the pre-v2 endpoints and v2 is that the newer version only returns a few fields by default, whereas standard, premi \ No newline at end of file diff --git a/x-api/migrate/overview.mdx b/x-api/migrate/overview.mdx index e319f2380..3049692dc 100644 --- a/x-api/migrate/overview.mdx +++ b/x-api/migrate/overview.mdx @@ -1,6 +1,7 @@ --- title: Overview keywords: ["migration", "API migration", "v2 migration", "migrate to v2", "migration guide", "upgrade to v2", "migration overview"] + --- import { Button } from "/snippets/button.mdx" @@ -72,141 +73,4 @@ The following six data objects are available with the v2 endpoints: |:--------|:-------------| | [Tweet](/x-api/fundamentals/data-dictionary#tweet) | The Tweet object has a long list of root-level fields, such as `id`, `text`, and `created_at`. Tweet objects are also the parent object to several child objects including `user`, `media`, `poll`, and `place`. | | [User](/x-api/fundamentals/data-dictionary#user) | The user object contains X user account metadata describing the referenced user. | -| [Spaces](/x-api/fundamentals/data-dictionary#space) | The Space object consists of fields such as `state`, `host_id`, `is_ticketed`, and even `lang`. | -| [Lists](/x-api/fundamentals/data-dictionary#list) | The List object contains basic information about the requested list including `description`, `member_count`, and `owner_id`. | -| [Media](/x-api/fundamentals/data-dictionary#media) | If a Tweet contains media (such as images), then the media object can be requested using the `media.fields` parameter and includes fields such as the `media_key`, `type`, `url`, `preview_image_url`, and more. | -| [Poll](/x-api/fundamentals/data-dictionary#poll) | A poll included in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet object. | -| [Place](/x-api/fundamentals/data-dictionary#place) | The place object consists of fields such as `place_id`, `geo` object, `country_code`, and more. This information can be used to identify Tweets and study Tweets by location. | - -Learn more about [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -### Flexibility to Choose Which Objects and Fields You Receive - -When making a request to a GET endpoint, you will receive the primary data object that relates to that endpoint, which will include a set of default fields. For example, the Tweet object delivers the `id` and `text` fields as its default. - -If you would like to retrieve additional fields with your request, you will have to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. The expansions parameter enables you to retrieve related data objects such as a user's pinned Tweet or a media object, while the field operators enable you to request specific fields within returned objects beyond the defaults. - -Here is a full list of expansions that you can request with the different X API v2 endpoints: - -| Object / Resource | Available Expansions | -|:-------------------|:----------------------| -| Tweets | `author_id`, `edit_history_tweet_ids`, `entities.mentions.username`, `in_reply_to_user_id`, `referenced_tweets.id`, `referenced_tweets.id.author_id`, `attachments.poll_ids`, `attachments.media_keys`, `geo.place_id` | -| Users | `pinned_tweet_id` | -| Spaces | `invited_user_ids`, `speaker_ids`, `creator_id`, `host_ids`, `topic_ids` | - -Learn more about [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -## New Metrics Available within Tweets, Users, Spaces, and Media Objects - -More metrics are now accessible within Tweet, user, Spaces, Lists, and media objects. These metrics are both public and private, and some metrics can be broken down into an organic or promoted context for Tweet ads. - -Learn more about the available [metrics](/x-api/fundamentals/metrics). - -| Object | Available Metrics | Public Metrics | Private Metrics | Organic Metrics | Promoted Metrics | -|:---------|:-------------------------|:----------------|:-----------------|:-----------------|:------------------| -| tweets | retweet_count | ✔️ | | ✔️ | ✔️ | -| | quote_count | ✔️ | | | | -| | like_count | ✔️ | | ✔️ | ✔️ | -| | reply_count | ✔️ | | ✔️ | ✔️ | -| | impression_count | | ✔️ | ✔️ | ✔️ | -| | url_profile_clicks | | ✔️ | ✔️ | ✔️ | -| | url_link_clicks | | ✔️ | ✔️ | ✔️ | -| user | follower_count | ✔️ | | | | -| user | following_count | ✔️ | | | | -| media | view_count | | ✔️ | | | -| media | playback_0_count | | ✔️ | | | -| space | participant_count | ✔️ | | | | - -## Edit Tweets - -The X API v2 endpoints provide edited Tweet metadata. The _Edit Tweet_ feature was first introduced for testing among X employees on September 1, 2022. Starting on that date, eligible Tweets are editable for 30 minutes and up to 5 times. Learn more about [Edit Tweets](/x-api/fundamentals/edit-posts). -Using the X API v2, a developer can find out: - -- If a Tweet was edit eligible at the time of creation. Some Tweets, such as those with polls or scheduled Tweets, can not be edited. -- Tweets are editable for 30 minutes, and can be edited up to 5 times. For editable Tweets you can see if time for editing remains and how many more edits are possible. -- If you are viewing an edited version of a Tweet (in most cases the API will return the most recent version of a Tweet, unless a specific past version is requested by Tweet ID). -- The entire edit history of the Tweet. -- The engagement attributed to each version of the Tweet. - -## Track Threaded Conversations - -A new Tweet field helps identify which conversation thread a Tweet belongs to. A conversation ID is the Tweet ID of the Tweet that started the conversation. Learn more about [conversation tracking](/x-api/fundamentals/conversation-id). - -## Ready to migrate - -In order to use v2 endpoints, you will need the following things: - -- [A developer account](https://developer.x.com/en/portal/petition/essential/basic-info) -- [A developer App](https://developer.x.com/en/apps) created within a [Project](resources/fundamentals/projects) -- [Keys and tokens](resources/fundamentals/authentication) from that Project’s developer App - -Please note the importance of using keys and tokens from an App within an App. If you are using keys and tokens from an App outside of a Project, you will not be able to make a request to v2 endpoints. - -Once you have a developer account, you can set up all of the above in the [Developer Console](https://developer.x.com/en/portal/petition/essential/basic-info). - -### Authentication -With the new Twitter API, you’ll use two different authentication patterns, OAuth 1.0a User Context and OAuth 2.0 Bearer Token, to access different endpoints. Each serves a different purpose when making requests to the endpoints: - -OAuth 1.0a User Context is required when making a request on behalf of a Twitter user -OAuth 2.0 Bearer token is required to make requests on behalf of your developer App - -## Tools and Code - -To help you get started and familiarize yourself with the new endpoints and capabilities we have a few options to jump start your work: - -- We have a Twitter [Postman collection](https://www.postman.com/xapidevelopers/x-api-public-workspace/collection/34902927-2efc5689-99c6-4ab6-8091-996f35c2fd80) that allows you to use the Postman client to make requests of and connect to the individual endpoints. This is a low-friction way to test authentication and experiment with the endpoints. -- We’ve also provided a list of both Twitter-supported and third-party libraries in Ruby, Python, Node, Java, and many more. For additional context, take a look at our [tools and libraries page](/tools-and-libraries). - -## Migrating to Updated Endpoints - -As you start to explore the new Twitter v2 endpoints, we’ve built a series of detailed migration guides to help you compare and contrast each updated endpoint's capabilities compared to older versions: - -- **Tweets** - - [Tweets lookup](/x-api/posts/lookup/integrate) - - [Manage Tweets](/x-api/posts/manage-tweets/migrate/overview) - - [Timelines](/x-api/posts/timelines/migrate/overview) - - [Search Tweets](/x-api/posts/search/migrate/overview) - - [Tweet counts](/x-api/posts/counts/migrate/overview) - - [Filtered stream](/x-api/posts/filtered-stream/migrate/overview) - - Sampled stream - - [Retweets](/x-api/posts/retweets/migrate/overview) - - [Likes](/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2) - - [Hide replies](/x-api/posts/hide-replies/migrate) -- **Users** - - [Users lookup](/x-api/users/lookup/migrate/overview) - - [Follows](/x-api/users/follows/migrate/standard-to-twitter-api-v2) - - [Blocks](/x-api/users/blocks/migrate) - - [Mutes](/x-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2) -- **Lists** - - [List lookup](/x-api/lists/list-lookup/migrate/overview) - - [Manage Lists](/x-api/lists/manage-lists/migrate/overview) - - [List Tweet lookup](/x-api/lists/list-tweets/migrate/overview) - - [List members](/x-api/lists/list-members/migrate/overview) - -## Migrating to the New Data Format - -As you move from v1.1 or enterprise to v2, it is important to understand that the format the data is delivered in has changed significantly. We have added new fields, modified the sequence of fields, and in some cases removed elements altogether. - -To learn more about these changes, we are developing a series of guides that will help you map out the pre-v2 data format fields to the newer fields, and describe how to request these new fields. - -You can learn more by visiting our [data formats migration](/x-api/migrate/data-format-migration) section of this migration hub, or by visiting our specific data format guides: - -- [Native format to x API v2 (standard v1.1)](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) -- [Native Enriched to X API v2 (enterprise)](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2) -- [Activity Streams to X API v2 (enterprise)](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) - -## What’s Next? - -Those of you who have used the platform for some time will notice that many of the new endpoints are aligned with existing [standard v1.1](https://developer.x.com/en/docs/twitter-api/v1) and [enterprise](/x-api/enterprise-gnip-2.0/enterprise-gnip) endpoints. Indeed, we intend for these to replace all three versions in the future. - -We’ve put together a table to help you understand how the [X API endpoints map](/x-api/migrate/x-api-endpoint-map) to previous versions. - -If you’d like to see what’s coming next, please visit our [product roadmap](https://trello.com/b/myf7rKwV/twitter-developer-platform-roadmap). - -We also have a [changelog](https://developer.x.com/en/updates/changelog) that you can check out to understand what we have already released. - -### What Should We Build Next? - -As we build out additional capabilities of the X API v2 we want to continue to hear from you. We welcome and encourage [feedback](https://twitterdevfeedback.uservoice.com/) from you. - -Take a look at the ideas that have already been submitted, show your support for those that correlate with your needs, and provide feedback as well! +| [Spaces](/x-api/fundamentals/data-dictionary#space) | The Space object consists of fields such \ No newline at end of file diff --git a/x-api/migrate/x-api-endpoint-map.mdx b/x-api/migrate/x-api-endpoint-map.mdx index 651c42c04..87f6985e0 100644 --- a/x-api/migrate/x-api-endpoint-map.mdx +++ b/x-api/migrate/x-api-endpoint-map.mdx @@ -1,7 +1,7 @@ --- title: X API endpoint map keywords: ["endpoint map", "API endpoint map", "v1.1 to v2", "endpoint mapping", "API mapping", "endpoint comparison"] ---- + The following table maps the X API v2 endpoints to the corresponding standard v1.1, and enterprise endpoints. To learn more about each of these versions and tiers, please visit our [X API getting started guide](/x-api/getting-started/about-x-api). @@ -21,47 +21,4 @@ You'll notice that we still have several items marked as **\[Coming Soon]**. If | | POST statuses/retweet/:id
POST statuses/unretweet/:id | | [Manage Retweets](/x-api/posts/retweets/introduction)
- Retweet a Tweet
- Undo a Retweet | | | GET favorites/list | | [Likes lookup](/x-api/posts/likes/introduction)
- Posts liked by a user
- Users who have liked a Post | | | POST favorites/create
POST favorites/destroy | | [Manage Likes](/x-api/posts/likes/introduction)
- Like a Post
- Unlike a Post | -| | | | [Hide replies](/x-api/posts/hide-replies/introduction) | -| | GET statuses/oembed | | \[No Replacement Planned] | -| | GET statuses/retweets\_of\_me | | \[No Replacement Planned] | -| **Users** | GET users/show
GET users/lookup | | [Users lookup](/x-api/users/lookup/introduction) | -| | GET users/search | | [Get user/search](/x-api/users/search/introduction) | -| | GET followers/ids
GET followers/list
GET friends/ids
GET friends/list | | [Follows lookup](/x-api/users/follows/introduction) | -| | GET friendships/incoming
GET friendships/lookup
GET friendships/no\_retweets/ids
GET friendships/outgoing
GET friendships/show | | [Connection\_status](/x-api/fundamentals/data-dictionary#user) | -| | GET friendships/create
GET friendships/destroy | | [Manage follows](/x-api/users/follows/introduction)
- Follow a user
- Unfollow a user | -| | POST friendships/update | | \[No Replacement Planned] | -| | GET blocks/ids
GET blocks/list | | [Blocks lookup](/x-api/users/blocks/introduction) | -| | POST blocks/create
POST blocks/destroy | | [Manage blocks](/x-api/users/blocks/introduction)
- Block a user
- Unblock a user | -| | GET mutes/users/ids
GET mutes/users/list | | [Mutes lookup](/x-api/users/mutes/introduction) | -| | POST mutes/users/create
POST mutes/users/destroy | | [Manage mutes](/x-api/users/mutes/introduction)
- Mute a user
- Unmute a user | -| | GET account/verify\_credentials | | \[No Changes Planned] | -| | | | \[No Replacement Planned] | -| | GET saved\_searches/show/:id
GET saved\_searches/list
POST saved\_searches/create
POST saved\_searches/destroy/:id | | \[No Replacement Planned] | -| | POST users/report\_spam | | \[No Replacement Planned] | -| | | [Account Activity API](/x-api/enterprise-gnip-2.0/fundamentals/account-activity) | \[Migrating in 2025] | -| **Spaces** | | | [Spaces lookup](/x-api/spaces/lookup/introduction) | -| | | | [Spaces search](/x-api/spaces/search/introduction) | -| | | | [Ticketed user lookup](/x-api/spaces/retrieve-the-list-of-users-who-purchased-a-ticket-to-the-given-space) | -| | | | [Tweets shared in a Space lookup](/x-api/spaces/retrieve-posts-from-a-space) | -| **Direct Messages** | | | [Direct Messages lookup](/x-api/direct-messages/lookup/introduction)
[Manage Direct Messages](/x-api/direct-messages/manage/introduction) | -| **Lists** | GET lists/show | | [Lists lookup](/x-api/lists/list-lookup/introduction) | -| | POST lists/create
POST lists/destroy
POST lists/update | | [Manage Lists](/x-api/lists/manage-lists/introduction) | -| | GET lists/statuses | | [Lists Tweets lookup](/x-api/posts/list-posts-timeline-by-list-id) | -| | GET lists/members
GET lists/memberships
POST lists/members/create
POST lists/members/destroy | | [List members](/x-api/lists/list-members#list-members-lookup) | -| | GET lists/subscribers
GET lists/subscriptions
GET lists/lists
POST lists/subscribers/create
POST lists/subscribers/destroy | | [Lists follows](/x-api/lists/manage-lists/introduction) | -| | GET lists/ownerships | | [Owned Lists lookup](/x-api/lists/list-lookup/introduction) | -| | | | [Pinned Lists](/x-api/lists/pinned-lists) | -| | GET lists/members/show
GET lists/subscribers/show | | \[No Replacement Planned] | -| | POST lists/members/create\_all
POST lists/members/destroy\_all | | \[No Replacement Planned] | -| **Media** | | | [Media Upload](https://docs.x.com/x-api/media/introduction) | -| **Trends** | | | [Trends v2](/x-api/trends/introduction) | -| **Geo** | | | \[No Replacement Planned] | -| **Collections** | GET collections/entries
GET collections/list
GET collections/show
POST collections/create
POST collections/destroy
POST collections/entries/add
POST collections/entries/curate
POST collections/entries/move
POST collections/entries/remove
POST collections/update | | \[No Replacement Planned] | -| **Metrics** | | [Engagement API](/enterprise-gnip-2.0/fundamentals/engagement-api)
- /totals
- /28hr
- /historical | /totals - [data is built into v2 responses](/x-api/fundamentals/metrics)
/28hr - \[[Here](https://docs.x.com/x-api/posts/get-last-28hr-metrics-for-posts#get-last-28hr-metrics-for-posts)]
/historical - \[[Here](https://docs.x.com/x-api/posts/get-historical-metrics-for-posts)] | -| **Compliance** | | | [Batch compliance](/x-api/compliance/batch-compliance/introduction) | -| | | [Compliance firehose](/x-api/enterprise-gnip-2.0/fundamentals/firehouse) | [Compliance streams](/x-api/compliance/streams/introduction) | -| **Utilities** | | [Usage API](/x-api/enterprise-gnip-2.0/fundamentals/usage) | [Usage API](/x-api/usage/introduction) | -| | GET application/rate\_limit\_status | | \[No Replacement Planned] | -| | GET help/languages | | \[No Replacement Planned] | -| **Authentication** | | | \[No Changes Planned] | -| **Streaming Likes** | | [Streaming Likes](/x-api/enterprise-gnip-2.0/fundamentals/decahose-api#streaming-likes) | \[Coming Soon] | \ No newline at end of file +| | | | [Hide replies](/x-api/posts/hide-replies/introduction) \ No newline at end of file diff --git a/x-api/news/get-news-stories-by-id.mdx b/x-api/news/get-news-stories-by-id.mdx index 9b814921a..dd9503dd2 100644 --- a/x-api/news/get-news-stories-by-id.mdx +++ b/x-api/news/get-news-stories-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/news/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/news/introduction.mdx b/x-api/news/introduction.mdx index 91205659a..c5b74d2cf 100644 --- a/x-api/news/introduction.mdx +++ b/x-api/news/introduction.mdx @@ -2,6 +2,8 @@ title: Introduction sidebarTitle: Introduction keywords: ["news", "news API", "headlines", "breaking news", "news lookup", "news stories", "news search"] + +description: The news lookup endpoint allows developers to get news and headlines breaking on X. This endpoint supports app-auth and user-auth authentication for OAuth1 a... --- The news lookup endpoint allows developers to get news and headlines breaking on X. diff --git a/x-api/news/search-news.mdx b/x-api/news/search-news.mdx index c8538ccc9..6f238e0ba 100644 --- a/x-api/news/search-news.mdx +++ b/x-api/news/search-news.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/news/search ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/bookmarks/integrate.mdx b/x-api/posts/bookmarks/integrate.mdx index 83cd200ab..914fc12c1 100644 --- a/x-api/posts/bookmarks/integrate.mdx +++ b/x-api/posts/bookmarks/integrate.mdx @@ -1,127 +1,40 @@ ---- -title: Integration guide -sidebarTitle: Integration guide -keywords: ["bookmarks integration", "bookmarks guide", "bookmarks integration guide", "bookmarks implementation", "bookmarks setup"] ---- - -import { Button } from '/snippets/button.mdx'; - -This page contains information on several tools and critical concepts that you should know as you integrate the manage Bookmarks endpoints into your system. We've broken the page into a couple of different sections: - -* [Helpful tools](/x-api/users/blocks/integrate#helpful-tools) -* Key Concepts - * [Authentication](/x-api/users/blocks/integrate#authentication) - * [Developer Console, Projects, and Apps](/x-api/users/blocks/integrate#Developer Console-projects-and-developer-apps) - * [Rate limits](/x-api/users/blocks/integrate#rate-limits) - -### Helpful tools - -Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: - -#### Postman - -Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. - -#### Code samples - -Are you interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). - -#### Third-party libraries - -Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. - -### Key concepts - -#### Authentication - -All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. - -These specific endpoints require the use of [OAuth 2.0 Authorization Code Flow with PKCE](/resources/fundamentals/authentication/oauth-2-0/authorization-code), which means that you must use a set of keys and user Access Tokens to make a successful request. The Access Tokens must be associated with the user that you are requesting on behalf of. If you want to generate a set of Access Tokens for another user, they must authorize or authenticate your App using an [Authorize URL](/resources/fundamentals/authentication#authorize-url). - -Please note that OAuth 2.0 can be tricky to use. If you are not familiar with this authentication method, we recommend using a [library](/tools-and-libraries) or a tool like Postman to properly authenticate your requests. - -#### Developer Console, Projects, and developer Apps - -To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must have a [developer account](/resources/fundamentals/developer-portal), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. - -#### Rate limits - -Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/resources/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. - -These endpoints are rate limited at the user level, meaning that the authenticated user that you are making the request on behalf of can only call the endpoint a certain number of times across any developer App. There is a user rate limit of 180 requests per 15 min window for the GET method. With the GET method of the Bookmarks lookup endpoint you will get back 800 of your most recent Bookmarked Posts. Additionally, there is a user rate limit of 50 requests per 15 minutes for the POST and DELETE methods. - ---- - -### Code examples - -#### Get bookmarks - - - -```bash cURL -curl "https://api.x.com/2/users/123/bookmarks?tweet.fields=created_at,public_metrics" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Get user's bookmarks -for page in client.bookmarks.get(user_id="123", tweet_fields=["created_at", "public_metrics"]): - for post in page.data: - print(f"{post.text} - Likes: {post.public_metrics.like_count}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -// Get user's bookmarks -const paginator = client.bookmarks.get("123", { - tweetFields: ["created_at", "public_metrics"], -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`${post.text} - Likes: ${post.public_metrics?.like_count}`); - }); -} -``` - - - -#### Create a bookmark - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123/bookmarks" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"tweet_id": "1234567890"}' -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Bookmark a Post -response = client.bookmarks.create(user_id="123", tweet_id="1234567890") -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -// Bookmark a Post -const response = await client.bookmarks.create("123", { tweetId: "1234567890" }); -console.log(response.data); -``` - - +--- +title: Integration guide +sidebarTitle: Integration guide +keywords: ["bookmarks integration", "bookmarks guide", "bookmarks integration guide", "bookmarks implementation", "bookmarks setup"] + + +--- +import { Button } from '/snippets/button.mdx'; + +This page contains information on several tools and critical concepts that you should know as you integrate the manage Bookmarks endpoints into your system. We've broken the page into a couple of different sections: + +* [Helpful tools](/x-api/users/blocks/integrate#helpful-tools) +* Key Concepts + * [Authentication](/x-api/users/blocks/integrate#authentication) + * [Developer Console, Projects, and Apps](/x-api/users/blocks/integrate#Developer Console-projects-and-developer-apps) + * [Rate limits](/x-api/users/blocks/integrate#rate-limits) + +### Helpful tools + +Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: + +#### Postman + +Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. + +#### Code samples + +Are you interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). + +#### Third-party libraries + +Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. + +### Key concepts + +#### Authentication + +All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. + +These specific endpoints require the \ No newline at end of file diff --git a/x-api/posts/counts/integrate/build-a-query.mdx b/x-api/posts/counts/integrate/build-a-query.mdx index 5bb139c24..386ff9a81 100644 --- a/x-api/posts/counts/integrate/build-a-query.mdx +++ b/x-api/posts/counts/integrate/build-a-query.mdx @@ -1,277 +1,190 @@ ---- -title: Build a query -sidebarTitle: Build a query -keywords: ["build query counts", "counts query", "query builder counts", "counts query syntax", "build counts query"] ---- - -#### Building a query - -**Query limitations!** - -Your queries will be limited depending on which [access level](/x-api/getting-started/about-x-api) you are using.  - -Your query can be 512 characters long for pay-per-use customers, or up to 4,096 characters for Enterprise customers. - -If you have Enterprise access, please reach out to your account manager.  - - -**Operator availability** - -While most operators are available to any developer, there are several that are reserved for those that have been approved for Enterprise access. We list which access level each operator is available to in the [list of operators](/x-api/posts/search/integrate/build-a-query) table using the following labels: - -* Core operators: Available when using any [Project](/resources/fundamentals/developer-apps). -* Advanced operators: Available when using a Project with Enterprise access  -   - -#### Operator types: standalone and conjunction-required - -**Standalone operators** can be used alone or together with any other operators (including those that require conjunction). - -For example, the following query will work because it uses the #hashtag operator, which is standalone: - -#xapiv2 - -**Conjunction-required** operators cannot be used by themselves in a query; they can only be used when at least one standalone operator is included in the query. This is because using these operators alone would be far too general, and would match on an extremely high volume of Posts. - -For example, the following queries are not supported since they contain only conjunction-required operators: - -has:media -has:links OR is:retweet - -If we add in a standalone operator, such as the phrase "X data", the query would then work properly.  - -"X data" has:mentions (has:media OR has:links) - -#### Boolean operators and grouping - -If you would like to string together multiple operators in a single query, you have the following tools at your disposal: - -| | | -| :--- | :--- | -| **AND logic** | Successive operators with a space between them will result in boolean "AND" logic, meaning that Posts will match only if both conditions are met. For example, snow day #NoSchool will match Posts containing the terms snow and day and the hashtag #NoSchool. | -| **OR logic** | Successive operators with OR between them will result in OR logic, meaning that Posts will match if either condition is met. For example, specifying grumpy OR cat OR #meme will match any Posts containing at least the terms grumpy or cat, or the hashtag #meme. | -| **NOT logic, negation** | Prepend a dash (-) to a keyword (or any operator) to negate it (NOT). For example, cat #meme -grumpy will match Posts containing the hashtag #meme and the term cat, but only if they do not contain the term grumpy. One common query clause is -is:retweet, which will not match on Retweets, thus matching only on original Posts, Quote Tweets, and replies. All operators can be negated, but negated operators cannot be used alone. | -| **Grouping** | You can use parentheses to group operators together. For example, (grumpy cat) OR (#meme has:images) will return either Posts containing the terms grumpy and cat, or Posts with images containing the hashtag #meme. Note that ANDs are applied first, then ORs are applied. | - -**A note on negations** - -The operators -is:nullcast must always be negated. - -Negated operators cannot be used alone. - -Do not negate a set of operators grouped together in a set of parentheses. Instead, negate each individual operator. For example, instead of using skiing -(snow OR day OR noschool), we suggest that you use skiing -snow -day -noschool.  - -**Order of operations** - -When combining AND and OR functionality, the following order of operations will dictate how your query is evaluated. - -1. Operators connected by AND logic are combined first -2. Then, operators connected with OR logic are applied - - - -For example: - -* apple OR iphone ipad would be evaluated as apple OR (iphone ipad) -* ipad iphone OR android would be evaluated as (iphone ipad) OR android - - - -To eliminate uncertainty and ensure that your query is evaluated as intended, group terms together with parentheses where appropriate.  - -For example: - -* (apple OR iphone) ipad -* iphone (ipad OR android) -   - -**Punctuation, diacritics, and case sensitivity** - -If you specify a keyword or hashtag query with character accents or diacritics, it will match Post text that contains both the term with the accents and diacritics, as well as those terms with normal characters. For example, queries with a keyword Diacrítica or hashtag #cumpleaños will match _Diacrítica_ or _#cumpleaños_, as well as with _Diacritica_ or _#cumpleanos_ without the tilde í or eñe. - -Characters with accents or diacritics are treated the same as normal characters and are not treated as word boundaries. For example, a query with the keyword cumpleaños would only match activities containing the word _cumpleaños_ and would not match activities containing _cumplea_, _cumplean_, or _os_. - -All operators are evaluated in a case-insensitive manner. For example, the query cat will match Posts with all of the following: _cat_, _CAT_, _Cat_. - -The [filtered stream](/x-api/posts/filtered-stream) matching behavior acts differently from Post counts. When [building a filtered stream rule](/x-api/posts/filtered-stream/integrate/build-a-rule), know that keywords and hashtags that include accents and diacritics will only match on terms that also include the accent and diacritic, and will not match on terms that use normal characters instead.  - -For example, filtered stream rules that include a keyword Diacrítica or hashtag #cumpleaños will only match the terms _Diacrítica_ and _#cumpleaños_, and will not match on _Diacritica_ or _#cumpleanos_ without the tilde í or eñe - -**Specificity and efficiency** - -When you start to build your query, it is important to keep a few things in mind. - -* Using broad, standalone operators for your query such as a single keyword or #hashtag is generally not recommended since it will likely match on a massive volume of Posts. Creating a more robust query will result in a more specific set of matching Posts, and will hopefully increase the accuracy of your Post counts to help you find more valuable insights.  - * For example, if your query was just the keyword happy you will likely get anywhere from 200,000 - 300,000 Posts per day. - * Adding more conditional operators narrows your results, for example (happy OR happiness) place_country:GB -birthday -is:retweet -* Writing efficient queries is also beneficial for staying within the characters query length restriction. The character count includes the entire query string including spaces and operators. - * For example, the following query is 59 characters long: (happy OR happiness) place_country:GB -birthday -is:retweet - - -**Quote Tweet matching behavior** - -When using the Post counts endpoints, operators will not match on the content from the original Post that was quoted, but will match on the content included in the Quote Tweet. - -However, please note that [filtered stream](/x-api/posts/filtered-stream) will match on both the content from the original Post that was quoted and the Quote Tweet's content. -  - -**Iteratively building a query** - -**Test your query early and often** - -Getting a query to return the "right" results the first time is rare. There is so much on X that may or may not be obvious at first and the query syntax described above may be hard to match to your desired query. - -As you build a query, it is important for you to periodically test it out using one of the [Search Post](/x-api/posts/search/introduction) endpoints to ensure that the Posts that are matching your query are relevant to your use case. - -For this section, we are going to start with the following query and adjust it based on the results that we receive during our test:  - -happy OR happiness - -**Use results to narrow the query** - -As you test the query with Search Posts, you should scan the returned Posts to see if they include the data that you are expecting and hoping to receive. Starting with a broad query and a superset of Post matches allows you to review the result and narrow the query to filter out undesired results.   - -When we tested the example query, we noticed that we were getting Posts in a variety of different languages. In this situation, we want to only receive Posts that are in english, so we’re going to add the lang: operator: - -(happy OR happiness) lang:en - -The test delivered a number of Posts wishing people a happy birthday, so we are going to add -birthday as a negated keyword operator. We also want to only receive original Posts, so we’ve added the negated -is:retweet operator: - -(happy OR happiness) lang:en -birthday -is:retweet - -**Adjust for inclusion where needed** - -If you notice that you are not receiving data via Search Posts that you expect and know that there are existing Posts that should return, you may need to broaden your query by removing operators that may be filtering out the desired data.  - -For our example, we noticed that there were other Posts in our personal timeline that expressed the emotion that we are looking for and weren’t included in the test results. To ensure we have greater coverage, we are going to add the keywords, excited and elated. - -(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet - -**Adjust for popular trends/bursts over the time period** - -Trends come and go on X quickly. Maintaining your query should be an active process. If you plan to use a query for a while, we suggest that you periodically check in on the data that you are receiving to see if you need to make any adjustments. - -In our example, we notice that we started to receive some Posts that are wishing people a “happy holidays”. Since we don’t want these Posts included in our results, we are going to add a negated -holidays keyword. - -(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays  - -Once you've properly tested and iterated upon your query, you can start sending it with the Post counts endpoints to start to receive just the volume of Posts rather than the full Post payloads. - -#### Adding a query to your request - -To add your query to your request, you must use the query parameter. As with any query parameters, you must make sure to HTTP encode the query that you developed. - -Here is an example of what this might look like using a cURL command. If you would like to use this command, please make sure to replace $BEARER_TOKEN with your own [Bearer Token](/resources/fundamentals/authentication#oauth-2-0): - - ``` - curl https://api.x.com/2/tweets/counts/recent?query=cat%20has%3Amedia%20-grumpy&tweet.fields=created_at&max_results=100 -H "Authorization: Bearer $BEARER_TOKEN" - ``` - - - -#### Query examples - -**Tracking a natural disaster** - -The following query matched on original Posts coming from weather agencies and gauges that discuss Hurricane Harvey, which hit Houston in 2017. - -Here is what the query would look like without the HTTP encoding: - -has:geo (from:NWSNHC OR from:NHC\_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS\_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet - - -And here is what the query would look like with the HTTP encoding, the query parameter, and the recent Post counts URI: - -https://api.x.com/2/tweets/counts/recent?query=-is%3Aretweet%20has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC\_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS\_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1) - -**Reviewing the sentiment of a conversation** - -The next rule could be used to better understand the sentiment of the conversation developing around the hashtag, _#nowplaying_, but scoped to just Posts published within North America. - -Here is what the two different queries, one for positive and one for negative, would look like without the HTTP encoding: - -#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place\_country:US OR place\_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing - -#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place\_country:US OR place\_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible - - -And here is what the query would look like with the HTTP encoding, the query parameter, and the recent Post counts URI: - -https://api.x.com/2/tweets/counts/recent?query=%23nowplaying%20(happy%20OR%20exciting%20OR%20excited%20OR%20favorite%20OR%20fav%20OR%20amazing%20OR%20lovely%20OR%20incredible)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-horrible%20-worst%20-sucks%20-bad%20-disappointing - -https://api.x.com/2/tweets/counts/recent?query=%23nowplaying%20(horrible%20OR%20worst%20OR%20sucks%20OR%20bad%20OR%20disappointing)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-happy%20-exciting%20-excited%20-favorite%20-fav%20-amazing%20-lovely%20-incredible - -**Find Posts that relate to a specific Post annotation** - -This rule was built to filter for original Posts that included an image of a pet that is not a cat, where the language identified in the Post is Japanese. To do this, we used the context: operator to take advantage of the[Post annotation](/x-api/fundamentals/post-annotations) functionality. We first used the[Post lookup](/x-api/posts/lookup/introduction) endpoint and the tweet.fields=context_annotations fields parameter to identify which domain.entity IDs we need to use in our query: - -* Posts that relate to cats return **domain** 66 (Interests and Hobbies category) with entity 852262932607926273 (Cats).  -* Posts that relate to pets return **domain** 65 (Interests and Hobbies Vertical) with entity 852262932607926273 (Pets).  - - -Here is what the query would look like without the HTTP encoding: - -context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja - - -And here is what the query would look like with the HTTP encoding, the query parameter, and the recent Post counts URI: - -https://api.x.com/2/tweets/counts/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja - -#### Operators - -| Operator | Type | Availability | Description | -|:------------------------|:--------------|:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `keyword` | Standalone | Core | Matches a keyword within the body of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body. Tokenization splits words based on punctuation, symbols, and Unicode basic plane separator characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your query. To match strings containing punctuation (for example coca-cola), symbol, or separator characters, you must wrap your keyword in double-quotes. Example: `pepsi OR cola OR "coca cola"` | -| `emoji` | Standalone | Core | Matches an emoji within the body of a Post. Similar to a keyword, emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body. Note that if an emoji has a variant, you must wrap it in double quotes to add to a query. Example: `(😃 OR 😡) 😬` | -| `"exact phrase match"` | Standalone | Core | Matches the exact phrase within the body of a Post. Example: `("X API" OR #v2) -"recent counts"` | -| `#` | Standalone | Core | Matches any Post containing a recognized hashtag, if the hashtag is a recognized entity in a Post. This operator performs an exact match, NOT a tokenized match, meaning the rule `#thanku` will match posts with the exact hashtag #thanku, but not those with the hashtag #thankunext. Example: `#thankunext #fanart OR @arianagrande` | -| `@` | Standalone | Core | Matches any Post that mentions the given username, if the username is a recognized entity (including the @ character). Example: `(@XDevelopers OR @API) -@X` | -| `$` | Standalone | Advanced | Matches any Post that contains the specified ‘cashtag’ (where the leading character of the token is the ‘$’ character). Note that the cashtag operator relies on X's ‘symbols’ entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself. Example: `$twtr OR @XDevelopers -$fb` | -| `from:` | Standalone | Core | Matches any Post from a specific user. The value can be either the username (excluding the @ character) or the user’s numeric user ID. You can only pass a single username/ID per `from:` operator. Example: `from:XDevelopers OR from:API -from:X` | -| `to:` | Standalone | Core | Matches any Post that is in reply to a particular user. The value can be either the username (excluding the @ character) or the user’s numeric user ID. You can only pass a single username/ID per `to:` operator. Example: `to:XDevelopers OR to:API -to:X` | -| `url:` | Standalone | Core | Performs a tokenized match on any validly-formatted URL of a Post. This operator can matches on the contents of both the `url` or `expanded_url` fields. For example, a Post containing "You should check out X Developer Labs: https://t.co/c0A36SWil4" (with the short URL redirecting to https://developer.x.com) will match both the following rules: `from:XDevelopers url:"https://developer.x.com"` and `from:XDevelopers url:"https://t.co"`. Tokens and phrases containing punctuation or special characters should be double-quoted. | -| `retweets_of:` | Standalone | Core | Matches Posts that are Retweets of the specified user. The value can be either the username (excluding the @ character) or the user’s numeric user ID. You can only pass a single username/ID per `retweets_of:` operator. Example: `retweets_of:XDevelopers OR retweets_of:API` | -| `context:` | Standalone | Core | Matches Posts with a specific domain id/entity id pair. You can only pass a single domain/entity per `context:` operator. Example: `context:domain_id.entity_id`. You can combine multiple domain/entities using the OR operator: `(context:47.113922 9372198469633 OR context:11.1088514520308342784)` | -| `entity:` | Standalone | Core | Matches Posts with a specific entity string value. You can only pass a single `entity:` operator. Example: `entity:"string declaration of entity/place"`. Please note that this is only available with recent search. | -| `conversation_id:` | Standalone | Core | Matches Posts that share a common conversation ID. A conversation ID is set to the Post ID of a Post that started a conversation. As Replies to a Post are posted, even Replies to Replies, the `conversation_id` is added to its JSON payload. You can only pass a single conversation ID per `conversation_id:` operator. Example: `conversation_id:1334987486343299072 (from:XDevelopers OR from:API)` | -| `list:` | Standalone | Advanced | Matches Posts posted by users who are members of a specified list. For example, if @XDevelopers and @API were members of List 123, and you included `list:123` in your query, your response will only contain Posts that have been published by those accounts. You can find List IDs by using the List lookup endpoint. Example: `list:123` | -| `place:` | Standalone | Advanced | Matches Posts tagged with the specified location or X place ID. Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes. You can only pass a single place per `place:` operator. Note: See the GET geo/search standard v1.1 endpoint for how to obtain X place IDs. Example: `place:"new york city" OR place:seattle OR place:fd70c22040963ac7` | -| `place_country:` | Standalone | Advanced | Matches Posts where the country code associated with a tagged place/location matches the given ISO alpha-2 character code. You can find a list of valid ISO codes on Wikipedia. You can only pass a single ISO code per `place_country:` operator. Example: `place_country:US OR place_country:MX OR place_country:CA` | -| `point_radius:` | Standalone | Advanced | Matches against the `place.geo.coordinates` object of the Post when present, and in X, against a place geo polygon, where the Place polygon is fully contained within the defined region. `point_radius:[longitude latitude radius]`. Units of radius supported are miles (mi) and kilometers (km). Radius must be less than 25mi. Longitude is in the range of ±180. Latitude is in the range of ±90. All coordinates are in decimal degrees. Rule arguments are contained within brackets, space delimited. Example: `point_radius:[2.355128 48.861118 16km] OR point_radius:[-41.287336 174.761070 20mi]` | -| `bounding_box:` | Standalone | Advanced | Matches against the place.geo.coordinates object of the Post when present, and in X, against a place geo polygon, where the place polygon is fully contained within the defined region. `bounding_box:[west_long south_lat east_long north_lat]`. Width and height of the bounding box must be less than 25mi. Longitude is in the range of ±180. Latitude is in the range of ±90. All coordinates are in decimal degrees. Rule arguments are contained within brackets, space delimited. Example: `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` | -| `is:retweet` | Conjunction required | Core | Matches on Retweets that match the rest of the specified rule. This operator looks only for true Retweets (for example, those generated using the Retweet button). Quote Tweets will not be matched by this operator. Example: `data @XDevelopers -is:retweet` | -| `is:reply` | Conjunction required | Core | Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a query from delivery. Note: This operator is also available with the filtered stream endpoint. When used with filtered stream, this operator matches on replies to an original Post, replies in quoted Posts, and replies in Retweets. Example: `from:XDevelopers is:reply` | -| `is:quote` | Conjunction required | Core | Returns all Quote Tweets, also known as Posts with comments. Example: `"sentiment analysis" is:quote` | -| `is:verified` | Conjunction required | Core | Deliver only Posts whose authors are verified by X. Example: `#nowplaying is:verified` | -| `-is :nullcast` | Conjunction required | Advanced | Removes Posts created for promotion only on ads.x.com that have a `"source":"Twitter for Advertisers (legacy)"` or `"source":"Twitter for Advertisers"`. This operator must be negated. For more info on Nullcasted Posts, see our page on Post availability. Example: `"mobile games" -is:nullcast` | -| `has:hashtags` | Conjunction required | Core | Matches Posts that contain at least one hashtag. Example: `from:XDevelopers -has:hashtags` | -| `has:cashtags` | Conjunction required | Advanced | Matches Posts that contain a cashtag symbol (with a leading ‘$’ character. For example, `$tag`). Example: `#stonks has:cashtags` | -| `has:links` | Conjunction required | Core | This operator matches Posts which contain links and media in the Post body. Example: `from:XDevelopers announcement has:links` | -| `has:mentions` | Conjunction required | Core | Matches Posts that mention another X user. Example: `#nowplaying has:mentions` | -| `has:media` | Conjunction required | Core | Matches Posts that contain a media object, such as a photo, GIF, or video, as determined by X. This will not match on media created with Periscope, or Posts with links to other media hosting sites. Example: `(kittens OR puppies) has:media` | -| `has:images` | Conjunction required | Core | Matches Posts that contain a recognized URL to an image. Example: `#meme has:images` | -| `has:videos` | Conjunction required | Core | Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Periscope, or Posts with links to other video hosting sites. Example: `#icebucketchallenge has:videos` | -| `has:geo` | Conjunction required | Advanced | Matches Posts that have Post-specific geolocation data provided by the X user. This can be either a location in the form of a X place, with the corresponding display name, geo polygon, and other fields, or in rare cases, a geo lat-long coordinate. Note: Operators matching on place (Post geo) will only include matches from original posts. Retweets do not contain any place data. Example: `recommend #paris has:geo -bakery` | -| `lang:` | Conjunction required | Core | Matches Posts that have been classified by X as being of a particular language (if, and only if, the Post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results. You can only pass a single BCP 47 language identifier per `lang:` operator. Note: if no language classification can be made the provided result is ‘und’ (for undefined). Example: `recommend #paris lang:en` | - -| | | | | -| :--- | :--- | :--- | :--- | -| Amharic: **am** | German: **de** | Malayalam: **ml** | Slovak: **sk** | -| Arabic: **ar** | Greek: **el** | Maldivian: **dv** | Slovenian: **sl** | -| Armenian: **hy** | Gujarati: **gu** | Marathi: **mr** | Sorani Kurdish: **ckb** | -| Basque: **eu** | Haitian Creole: **ht** | Nepali: **ne** | Spanish: **es** | -| Bengali: **bn** | Hebrew: **iw** | Norwegian: **no** | Swedish: **sv** | -| Bosnian: **bs** | Hindi: **hi** | Oriya: **or** | Tagalog: **tl** | -| Bulgarian: **bg** | Latinized Hindi: **hi-Latn** | Panjabi: **pa** | Tamil: **ta** | -| Burmese: **my** | Hungarian: **hu** | Pashto: **ps** | Telugu: **te** | -| Croatian: **hr** | Icelandic: **is** | Persian: **fa** | Thai: **th** | -| Catalan: **ca** | Indonesian: **in** | Polish: **pl** | Tibetan: **bo** | -| Czech: **cs** | Italian: **it** | Portuguese: **pt** | Traditional Chinese: **zh-TW** | -| Danish: **da** | Japanese: **ja** | Romanian: **ro** | Turkish: **tr** | -| Dutch: **nl** | Kannada: **kn** | Russian: **ru** | Ukrainian: **uk** | -| English: **en** | Khmer: **km** | Serbian: **sr** | Urdu: **ur** | -| Estonian: **et** | Korean: **ko** | Simplified Chinese: **zh-CN** | Uyghur: **ug** | -| Finnish: **fi** | Lao: **lo** | Sindhi: **sd** | Vietnamese: **vi** | -| French: **fr** | Latvian: **lv** | Sinhala: **si** | Welsh: **cy** | -| Georgian: **ka** | Lithuanian: **lt** | | +--- +title: Build a query +sidebarTitle: Build a query +keywords: ["build query counts", "counts query", "query builder counts", "counts query syntax", "build counts query"] + +description: **Query limitations! ** Your queries will be limited depending on which [access level](/x-api/getting-started/about-x-api) you are using.--- + +#### Building a query + +**Query limitations!** + +Your queries will be limited depending on which [access level](/x-api/getting-started/about-x-api) you are using.  + +Your query can be 512 characters long for pay-per-use customers, or up to 4,096 characters for Enterprise customers. + +If you have Enterprise access, please reach out to your account manager.  + + +**Operator availability** + +While most operators are available to any developer, there are several that are reserved for those that have been approved for Enterprise access. We list which access level each operator is available to in the [list of operators](/x-api/posts/search/integrate/build-a-query) table using the following labels: + +* Core operators: Available when using any [Project](/resources/fundamentals/developer-apps). +* Advanced operators: Available when using a Project with Enterprise access  +   + +#### Operator types: standalone and conjunction-required + +**Standalone operators** can be used alone or together with any other operators (including those that require conjunction). + +For example, the following query will work because it uses the #hashtag operator, which is standalone: + +#xapiv2 + +**Conjunction-required** operators cannot be used by themselves in a query; they can only be used when at least one standalone operator is included in the query. This is because using these operators alone would be far too general, and would match on an extremely high volume of Posts. + +For example, the following queries are not supported since they contain only conjunction-required operators: + +has:media +has:links OR is:retweet + +If we add in a standalone operator, such as the phrase "X data", the query would then work properly.  + +"X data" has:mentions (has:media OR has:links) + +#### Boolean operators and grouping + +If you would like to string together multiple operators in a single query, you have the following tools at your disposal: + +| | | +| :--- | :--- | +| **AND logic** | Successive operators with a space between them will result in boolean "AND" logic, meaning that Posts will match only if both conditions are met. For example, snow day #NoSchool will match Posts containing the terms snow and day and the hashtag #NoSchool. | +| **OR logic** | Successive operators with OR between them will result in OR logic, meaning that Posts will match if either condition is met. For example, specifying grumpy OR cat OR #meme will match any Posts containing at least the terms grumpy or cat, or the hashtag #meme. | +| **NOT logic, negation** | Prepend a dash (-) to a keyword (or any operator) to negate it (NOT). For example, cat #meme -grumpy will match Posts containing the hashtag #meme and the term cat, but only if they do not contain the term grumpy. One common query clause is -is:retweet, which will not match on Retweets, thus matching only on original Posts, Quote Tweets, and replies. All operators can be negated, but negated operators cannot be used alone. | +| **Grouping** | You can use parentheses to group operators together. For example, (grumpy cat) OR (#meme has:images) will return either Posts containing the terms grumpy and cat, or Posts with images containing the hashtag #meme. Note that ANDs are applied first, then ORs are applied. | + +**A note on negations** + +The operators -is:nullcast must always be negated. + +Negated operators cannot be used alone. + +Do not negate a set of operators grouped together in a set of parentheses. Instead, negate each individual operator. For example, instead of using skiing -(snow OR day OR noschool), we suggest that you use skiing -snow -day -noschool.  + +**Order of operations** + +When combining AND and OR functionality, the following order of operations will dictate how your query is evaluated. + +1. Operators connected by AND logic are combined first +2. Then, operators connected with OR logic are applied + + + +For example: + +* apple OR iphone ipad would be evaluated as apple OR (iphone ipad) +* ipad iphone OR android would be evaluated as (iphone ipad) OR android + + + +To eliminate uncertainty and ensure that your query is evaluated as intended, group terms together with parentheses where appropriate.  + +For example: + +* (apple OR iphone) ipad +* iphone (ipad OR android) +   + +**Punctuation, diacritics, and case sensitivity** + +If you specify a keyword or hashtag query with character accents or diacritics, it will match Post text that contains both the term with the accents and diacritics, as well as those terms with normal characters. For example, queries with a keyword Diacrítica or hashtag #cumpleaños will match _Diacrítica_ or _#cumpleaños_, as well as with _Diacritica_ or _#cumpleanos_ without the tilde í or eñe. + +Characters with accents or diacritics are treated the same as normal characters and are not treated as word boundaries. For example, a query with the keyword cumpleaños would only match activities containing the word _cumpleaños_ and would not match activities containing _cumplea_, _cumplean_, or _os_. + +All operators are evaluated in a case-insensitive manner. For example, the query cat will match Posts with all of the following: _cat_, _CAT_, _Cat_. + +The [filtered stream](/x-api/posts/filtered-stream) matching behavior acts differently from Post counts. When [building a filtered stream rule](/x-api/posts/filtered-stream/integrate/build-a-rule), know that keywords and hashtags that include accents and diacritics will only match on terms that also include the accent and diacritic, and will not match on terms that use normal characters instead.  + +For example, filtered stream rules that include a keyword Diacrítica or hashtag #cumpleaños will only match the terms _Diacrítica_ and _#cumpleaños_, and will not match on _Diacritica_ or _#cumpleanos_ without the tilde í or eñe + +**Specificity and efficiency** + +When you start to build your query, it is important to keep a few things in mind. + +* Using broad, standalone operators for your query such as a single keyword or #hashtag is generally not recommended since it will likely match on a massive volume of Posts. Creating a more robust query will result in a more specific set of matching Posts, and will hopefully increase the accuracy of your Post counts to help you find more valuable insights.  + * For example, if your query was just the keyword happy you will likely get anywhere from 200,000 - 300,000 Posts per day. + * Adding more conditional operators narrows your results, for example (happy OR happiness) place_country:GB -birthday -is:retweet +* Writing efficient queries is also beneficial for staying within the characters query length restriction. The character count includes the entire query string including spaces and operators. + * For example, the following query is 59 characters long: (happy OR happiness) place_country:GB -birthday -is:retweet + + +**Quote Tweet matching behavior** + +When using the Post counts endpoints, operators will not match on the content from the original Post that was quoted, but will match on the content included in the Quote Tweet. + +However, please note that [filtered stream](/x-api/posts/filtered-stream) will match on both the content from the original Post that was quoted and the Quote Tweet's content. +  + +**Iteratively building a query** + +**Test your query early and often** + +Getting a query to return the "right" results the first time is rare. There is so much on X that may or may not be obvious at first and the query syntax described above may be hard to match to your desired query. + +As you build a query, it is important for you to periodically test it out using one of the [Search Post](/x-api/posts/search/introduction) endpoints to ensure that the Posts that are matching your query are relevant to your use case. + +For this section, we are going to start with the following query and adjust it based on the results that we receive during our test:  + +happy OR happiness + +**Use results to narrow the query** + +As you test the query with Search Posts, you should scan the returned Posts to see if they include the data that you are expecting and hoping to receive. Starting with a broad query and a superset of Post matches allows you to review the result and narrow the query to filter out undesired results.   + +When we tested the example query, we noticed that we were getting Posts in a variety of different languages. In this situation, we want to only receive Posts that are in english, so we’re going to add the lang: operator: + +(happy OR happiness) lang:en + +The test delivered a number of Posts wishing people a happy birthday, so we are going to add -birthday as a negated keyword operator. We also want to only receive original Posts, so we’ve added the negated -is:retweet operator: + +(happy OR happiness) lang:en -birthday -is:retweet + +**Adjust for inclusion where needed** + +If you notice that you are not receiving data via Search Posts that you expect and know that there are existing Posts that should return, you may need to broaden your query by removing operators that may be filtering out the desired data.  + +For our example, we noticed that there were other Posts in our personal timeline that expressed the emotion that we are looking for and weren’t included in the test results. To ensure we have greater coverage, we are going to add the keywords, excited and elated. + +(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet + +**Adjust for popular trends/bursts over the time period** + +Trends come and go on X quickly. Maintaining your query should be an active process. If you plan to use a query for a while, we suggest that you periodically check in on the data that you are receiving to see if you need to make any adjustments. + +In our example, we notice that we started to receive some Posts that are wishing people a “happy holidays”. Since we don’t want these Posts included in our results, we are going to add a negated -holidays keyword. + +(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays  + +Once you've properly tested and iterated upon your query, you can start sending it with the Post counts endpoints to start to receive just the volume of Posts rather than the full Post payloads. + +#### Adding a query to your request + +To add your query to your request, you must use the query parameter. As with any query parameters, you must make sure to HTTP encode the query that you developed. + +Here is an example of what this might look like using a cURL command. If you would like to use this command, please make sure to replace $BEARER_TOKEN with your own [Bearer Token](/resources/fundamentals/authentication#oauth-2-0): + + ``` + curl https://api.x.com/2/tweets/counts/recent?query=cat%20has%3Amedia%20-grumpy&tweet.fields=created_at&max_results=100 -H "Authorization: Bearer $BEARER_TOKEN" + ``` + + + +#### Query examples + +**Tracking a natural disaster** + +The following query matched on original Posts coming from weather agencies and gauges that discuss Hurricane Harvey, which hit Houston in 2017. + +Here is what the query would look like without the HTTP encoding: + +has:geo (from:NWSNHC OR from:NHC\_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS\_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet + + +And here is what the query would look like with the HTTP encoding, the query parameter, and the recent Post counts URI: + +https://api.x.com/2/tweets/counts/recent?query=-is%3Aretweet%20has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC\_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS\_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1) + +**Reviewing the sentiment of a conversation** + +The next rule could be used to better understand the sentiment of the conversation developing around the hashtag, _#nowplaying_, but scoped to just Posts published within \ No newline at end of file diff --git a/x-api/posts/counts/integrate/overview.mdx b/x-api/posts/counts/integrate/overview.mdx index f08124351..4d0e2d495 100644 --- a/x-api/posts/counts/integrate/overview.mdx +++ b/x-api/posts/counts/integrate/overview.mdx @@ -1,57 +1,55 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["post counts integration", "tweet counts integration", "counts overview", "counts integration guide", "tweet volume integration"] ---- - -This page covers tools and key concepts for integrating the Post counts endpoints. - ---- - -## Helpful tools - -Before we start to explore some key concepts, we recommend that you use one of the following tools or code samples to start testing the functionality of these endpoints. - -### Code samples - -Interested in getting set up with these endpoints with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [GitHub page](https://github.com/xdevplatform/Twitter-API-v2-sample-code), including a [Python client](https://github.com/xdevplatform/search-tweets-python). - -### Libraries - -Take advantage of one of our many [community third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the appropriate version tag. - -### Postman - -Postman is a great tool that you can use to test out these endpoints. Each Postman request includes all of the given endpoint's parameters to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our [Using Postman](/tutorials/postman-getting-started) page. - ---- - -## Key concepts - -### Authentication - -All X API v2 endpoints require requests to be [authenticated](/resources/fundamentals/authentication) with a set of credentials, also known as keys and tokens. This specific endpoint requires the use of [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#oauth-2-0), which means that you must pass a [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only) to make a successful request. You can either generate a Bearer Token from directly within a developer App, or generate one using the [POST oauth2/token](/resources/fundamentals/authentication#post-oauth2-token) endpoint. - -### Developer Console, Projects, and developer Apps - -To work with any X API v2 endpoints, you must have a [developer account](/resources/fundamentals/developer-portal), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. Your keys and tokens within that developer App will work for the recent Post counts endpoints. If you would like to use the full-archive Post counts endpoint, or utilize the advanced operators and longer query length, you will need to have been approved for enterprise access. - -Please visit our section on enterprise access to learn more. - -### Rate limits - -Every day, many thousands of developers make requests to the X API. To help manage the volume, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests that every developer can make on behalf of an app or on behalf of an authenticated user. - -This endpoint is rate limited at the App-level, meaning that you, the developer, can only make a certain number of requests to this endpoint over a given period of time from any given App (assumed by the credentials that you are using). - -### Building queries - -The central feature of these endpoints is their use of a single query to filter the Posts into the counts that deliver to you. These queries are made up of operators that match on Post and user attributes, such as message keywords, hashtags, and URLs. Operators can be combined into queries with boolean logic and parentheses to help refine the query's matching behavior. - -You can use our guide on [how to build a query](/x-api/posts/counts/integrate/build-a-query) to learn more. - -### Pagination - -For recent Post counts, there is no next_token returned, which means that regardless of the granularity, you will get the Post volume for the last 7 days in one API call. - -For full-archive Post counts, you will get data for the last 30 days. For data more than 30 days, you will get a next_token which you can then use to paginate to get the additional data. +--- +title: Overview +sidebarTitle: Overview +keywords: ["post counts integration", "tweet counts integration", "counts overview", "counts integration guide", "tweet volume integration"] +--- + +This page covers tools and key concepts for integrating the Post counts endpoints. + +## Helpful tools + +Before we start to explore some key concepts, we recommend that you use one of the following tools or code samples to start testing the functionality of these endpoints. + +### Code samples + +Interested in getting set up with these endpoints with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [GitHub page](https://github.com/xdevplatform/Twitter-API-v2-sample-code), including a [Python client](https://github.com/xdevplatform/search-tweets-python). + +### Libraries + +Take advantage of one of our many [community third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the appropriate version tag. + +### Postman + +Postman is a great tool that you can use to test out these endpoints. Each Postman request includes all of the given endpoint's parameters to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our [Using Postman](/tutorials/postman-getting-started) page. + +--- + +## Key concepts + +### Authentication + +All X API v2 endpoints require requests to be [authenticated](/resources/fundamentals/authentication) with a set of credentials, also known as keys and tokens. This specific endpoint requires the use of [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#oauth-2-0), which means that you must pass a [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only) to make a successful request. You can either generate a Bearer Token from directly within a developer App, or generate one using the [POST oauth2/token](/resources/fundamentals/authentication#post-oauth2-token) endpoint. + +### Developer Console, Projects, and developer Apps + +To work with any X API v2 endpoints, you must have a [developer account](/resources/fundamentals/developer-portal), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. Your keys and tokens within that developer App will work for the recent Post counts endpoints. If you would like to use the full-archive Post counts endpoint, or utilize the advanced operators and longer query length, you will need to have been approved for enterprise access. + +Please visit our section on enterprise access to learn more. + +### Rate limits + +Every day, many thousands of developers make requests to the X API. To help manage the volume, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests that every developer can make on behalf of an app or on behalf of an authenticated user. + +This endpoint is rate limited at the App-level, meaning that you, the developer, can only make a certain number of requests to this endpoint over a given period of time from any given App (assumed by the credentials that you are using). + +### Building queries + +The central feature of these endpoints is their use of a single query to filter the Posts into the counts that deliver to you. These queries are made up of operators that match on Post and user attributes, such as message keywords, hashtags, and URLs. Operators can be combined into queries with boolean logic and parentheses to help refine the query's matching behavior. + +You can use our guide on [how to build a query](/x-api/posts/counts/integrate/build-a-query) to learn more. + +### Pagination + +For recent Post counts, there is no next_token returned, which means that regardless of the granularity, you will get the Post volume for the last 7 days in one API call. + +For full-archive Post counts, you will get data for the last 30 days. For data more than 30 days, you will get a next_token which you can then use to paginate to get the additional data. diff --git a/x-api/posts/counts/migrate/enterprise-to-twitter-api-v2.mdx b/x-api/posts/counts/migrate/enterprise-to-twitter-api-v2.mdx index 49962a48d..fab75181c 100644 --- a/x-api/posts/counts/migrate/enterprise-to-twitter-api-v2.mdx +++ b/x-api/posts/counts/migrate/enterprise-to-twitter-api-v2.mdx @@ -1,131 +1,58 @@ ---- -title: v1 to v2 (Enterprise) -sidebarTitle: v1 to v2 (Enterprise) -keywords: ["enterprise to v2 counts", "enterprise counts migration", "GNIP to v2 counts", "enterprise counts migration", "migrate enterprise counts"] ---- - -### Enterprise compared to X API v2 - -**Similarities** - -* Granularity -* Pagination -* Timezone - -**Differences** - -* Endpoint URLs -* App and Project requirement -* Available time periods -* Response data format -* HTTP methods -* Request time formats -* Request parameters -* Filtering operators - -#### Similarities - -**Granularity** - -While the parameter for selecting granularity of the returned data is different (`bucket` for the enterprise version, `granularity` for the v2 version), the values that you can pass with that parameter are the same, as well as the default behavior: - -* `day` -* `hour` (default) -* `minute` - -**Pagination** - -While v2 has additional pagination features (new pagination parameters that allow you to navigate using Post IDs with `since_id` and `until_id`), both enterprise and v2 allow you to paginate using time (`fromDate` and `toDate` with enterprise, and `start_time` and `end_time` for v2). - -If you are using the enterprise version, you will use the `next` parameter to paginate, the next token field will be called `next`, and it will be located at the root in the response. - -If you are using v2, you can use either the `next_token` or `pagination_token` parameter to paginate, and your next token will be located at `meta.next_token` in the response. -  - -**Timezone** - -As noted in the pagination section, you can navigate different pages of data using time for both enterprise and v2. In both cases, you will be using UTC as the timezone when using these parameters. - -#### Differences - -**Endpoint URLs** - -* Enterprise endpoints: - * 30 day - `http://gnip-api.x.com/search/30day/accounts/:account_name/:label/counts.json` - * Full-archive - `http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label/counts.json` -* X API v2 endpoints - * Recent (7 day) - `https://api.x.com/2/tweets/counts/recent` - * Full-archive - `https://api.x.com/2/tweets/counts/all` - -**App and Project requirement** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. -  - -**Available time periods** - -Both the enterprise API and X API v2 offer endpoints that allow you to retrieve Post volume data for the full-archive of Posts. - -However, the X API v2 does not offer a 30 day time period endpoint like the enterprise API does. Instead it offers the aforementioned full-archive, or a 7 day time period, which align with the [v2 Search Posts endpoints](/x-api/posts/search/introduction). -  - -**Response data format** - -There are some slight differences in the data format that you will receive via enterprise and X API v2: - -* Enterprise’s counts data is located within a `results` object, while the v2 counts data is located within a data object. -* Enterprise’s counts fields are called `timePeriod` (start time) and `count`, while v2 breaks out the time period into a `start` and `end` field (which use a different date/time format from enterprise explained in request time formats), and renamed the count field to `tweet_count`. -* The enterprise metadata includes `totalCount`, `next`, and the `requestParameters` object at the root level. Instead,v2 doesn’t include the requestParameters object, and moves/renames the following into a `meta` object that lives at the root level: `total_tweet_count` & `next_token`. -   - -**HTTP methods** - -The enterprise version of the API allows you to pass the request as either a POST HTTP method with a JSON body, or a GET HTTP method with a query string. - -V2 only allows you to use the GET HTTP method with a query string. -  - -**Request time formats** - -The enterprise version of this endpoint uses the following date/time format in both the pagination parameters and the `timePeriod` response field: `YYYYMMDDHHmm` - -The v2 endpoint uses ISO 8601/RFC 3339 date/time format in both the pagination parameters and the `start` and `end` response fields: `YYYY-MM-DDTHH:mm:ssZ` - -**Request parameters** - -The following is a table of the request parameters for enterprise and X API v2: - -| Enterprise | Search Posts v2 | -| :--- | :--- | -| query | query | -| bucket | granularity | -| fromDate (YYMMDDHHmm) | start_time (YYYY-MM-DDTHH:mm:ssZ) | -| toDate (YYMMDDHHmm) | end_time (YYYY-MM-DDTHH:mm:ssZ) | -| | since_id | -| | until_id | -| next | next\_token and pagination\_token | - -**Filtering operators** - -While the operators between enterprise and X API v2 are mostly the same, there are some differences in operator availability and some new operators that were introduced to just the X API v2 version. - -To see a full table of the operators that are available for X API v2, enterprise, and even premium, please visit the [Post counts migration landing page](/x-api/posts/counts/migrate/overview). - - -## API reference index - -For a complete API reference, please select an endpoint from below. - -### Recent Post counts - -| | | -| :--- | :--- | -| **Receive a count of Posts that match a query in the last 7 days** | `[GET /2/tweets/counts/recent](/x-api/posts/tweet-counts#api-reference-index/get-tweets-counts-recent)` | - -### Full-archive Post counts - -Only available to those with [Self-serve and Enterprise access](/x-api/getting-started/about-x-api) - -| | | -| :--- | :--- | -| **Receive a count of Posts that match a query** | `[GET /2/tweets/counts/all](/x-api/posts/tweet-counts#api-reference-index/get-tweets-counts-all)` | +--- +title: v1 to v2 (Enterprise) +sidebarTitle: v1 to v2 (Enterprise) +keywords: ["enterprise to v2 counts", "enterprise counts migration", "GNIP to v2 counts", "enterprise counts migration", "migrate enterprise counts"] + + +--- +### Enterprise compared to X API v2 + +**Similarities** + +* Granularity +* Pagination +* Timezone + +**Differences** + +* Endpoint URLs +* App and Project requirement +* Available time periods +* Response data format +* HTTP methods +* Request time formats +* Request parameters +* Filtering operators + +#### Similarities + +**Granularity** + +While the parameter for selecting granularity of the returned data is different (`bucket` for the enterprise version, `granularity` for the v2 version), the values that you can pass with that parameter are the same, as well as the default behavior: + +* `day` +* `hour` (default) +* `minute` + +**Pagination** + +While v2 has additional pagination features (new pagination parameters that allow you to navigate using Post IDs with `since_id` and `until_id`), both enterprise and v2 allow you to paginate using time (`fromDate` and `toDate` with enterprise, and `start_time` and `end_time` for v2). + +If you are using the enterprise version, you will use the `next` parameter to paginate, the next token field will be called `next`, and it will be located at the root in the response. + +If you are using v2, you can use either the `next_token` or `pagination_token` parameter to paginate, and your next token will be located at `meta.next_token` in the response. +  + +**Timezone** + +As noted in the pagination section, you can navigate different pages of data using time for both enterprise and v2. In both cases, you will be using UTC as the timezone when using these parameters. + +#### Differences + +**Endpoint URLs** + +* Enterprise endpoints: + * 30 day - `http://gnip-api.x.com/search/30day/accounts/:account_name/:label/counts.json` + * Full-archive - `http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label/counts.json` +* X API v2 endpoints + * \ No newline at end of file diff --git a/x-api/posts/counts/migrate/overview.mdx b/x-api/posts/counts/migrate/overview.mdx index 9ff58803a..926b04d87 100644 --- a/x-api/posts/counts/migrate/overview.mdx +++ b/x-api/posts/counts/migrate/overview.mdx @@ -1,136 +1,135 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["counts migration", "tweet counts migration", "v1.1 to v2 counts", "counts migration guide", "migrate counts"] ---- - -## Comparing X API’s Post counts endpoints - -The v2 Post counts endpoint will eventually replace the [enterprise Search API’s counts endpoint](/x-api/enterprise-gnip-2.0/fundamentals/search-api#counts-requests-post-count). If you have code, apps, or tools that use an older version of a Post counts endpoint and are considering migrating to the newer X API v2 endpoints, then this guide is for you. - ---- - -## Recent Post counts comparison - -The enterprise version of the Post counts endpoints allow you to pull counts for either 30 days or from the full-archive. Therefore, the v2 recent Post counts endpoint, which looks at a 7 day time period, is not a direct replacement for either of the aforementioned endpoints. - -However, to help with comparisons, we will look at how the v2 recent Post counts endpoint compares to the enterprise 30-day endpoint. - -The following table compares the various types of recent Post counts endpoints: - -| **Description** | **Enterprise** | **X API v2** | -| :--- | :--- | :--- | -| Host domain | https://gnip-api.x.com | https://api.x.com | -| Endpoint path | /search/30day/accounts/:account_name/:label/counts.json | /2/tweets/counts/recent | -| [Authentication](/resources/fundamentals/authentication) | Basic authentication | OAuth 2.0 Bearer Token | -| Timestamp format | YYYYMMDDhhmm | YYYY-MM-DDTHH:mm:ssZ
[ISO 8601 / RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6) | -| Returns counts of Posts that are no older than | 31 days | 7 days | -| HTTP methods supported | GET | GET | -| Default request rate limits | 20 requests per 1 sec, aggregated across search data and counts requests
The per minute rate limit will vary by partner as specified in your contract. | 180 requests per 15 min per user
450 requests per 15 min per App | -| Supports filtering using [annotations](/x-api/fundamentals/post-annotations) | | ✔ | -| Supports filtering using [conversation_id](/x-api/fundamentals/conversation-id) | | ✔ | -| JSON key name for Post data array | results | data | -| Time granularity | Day, hour, or minute | Day, hour, or minute | -| Timezone | UTC | UTC | -| Request parameters for selecting time period | fromDate
toDate | start_time
end_time | -| Request parameters for navigating by Post ID | | since_id
until_id | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [project](/resources/fundamentals/developer-apps) | | ✔ | - -### Full-archive Post counts comparison - -The following table compares the various types of full-archive search endpoints: - -| Description | Enterprise | X API v2 | -| :--- | :--- | :--- | -| Host domain | https://gnip-api.x.com | https://api.x.com | -| Endpoint path | /search/fullarchive/accounts/:account_name/:label/counts | /2/tweets/counts/all | -| [Authentication](/resources/fundamentals/authentication) | Basic auth | OAuth 2.0 Bearer Token | -| Timestamp format | YYYYMMDDHHMM | YYYY-MM-DDTHH:mm:ssZ
[ISO 8601 / RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6) | -| Returns Post counts that are no older than | The full archive since March 2006 | The full archive since March 2006 | -| HTTP methods supported | GET
POST | GET | -| Default request rate limits | The per minute rate limit will vary by partner as specified in your contract.
20 requests per sec | 300 requests per 15 min per App
1 request per 1 sec per App | -| Granularity | Day, hour, minute | Day, hour, minute | -| Supports filtering using [annotations](/x-api/fundamentals/post-annotations) | | ✔ | -| Supports filtering using [conversation_id](/x-api/fundamentals/conversation-id) | | ✔ | -| JSON key name for Post data array | results | data | -| Request parameters for selecting time period | fromDate
toDate | start_time
end_time | -| Request parameters for navigating by Post ID | | since_id
until_id | -| JSON key name for pagination | next | meta.next_token | -| Request parameter for pagination | next_token | next_token or pagination_token | -| Timezone | UTC | UTC | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) that has [Academic Research access](/x-api/getting-started/about-x-api) | | ✔ | - -### Filtering operator comparison - -The two different versions (enterprise, and v2) of Post counts differ in which operators are available, and also have varying levels of operator availability within each version, which are explained below. - -Enterprise - -* There are no sub-tiers of enterprise operators. All enterprise operators are available to all enterprise users. - - - -X API v2 - -* **Core:** These operators are available to any v2 user. -* **Advanced:** These operators are only available to users that have been approved for Academic Research access. - - - -You can learn more about each of these sets of operators in their respective guides: - -* [Enterprise operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#building-search-queries) -* [X API v2 operators](/x-api/posts/search/integrate/build-a-query) - - - -Now that we understand these different operator levels within X API v2, here is the table that maps out operator availability for Post counts (note that if the cell is left blank, the operator is not available): - -| | Enterprise | v2 | -| :--- | :--- | :--- | -| keyword | Available | Core | -| emoji | Available | Core | -| “exact phrase” | Available | Core | -| # | Available | Core | -| $ | Available | Advanced | -| @ | Available | Core | -| from: | Available | Core | -| to: | Available | Core | -| url: | Available | Core | -| retweets_of: | Available | Core | -| context: | | Core | -| entity: | | Core - Only available with recent search | -| conversation_id: | | Core | -| place: | Available | Advanced | -| place_country: | Available | Advanced | -| point_radius: | Available | Advanced | -| bounding_box: | Available | Advanced | -| is:retweet | Available | Core | -| is:reply | Available | Core | -| is:quote | Available | Core | -| is:verified | Available | Core | -| -is:nullcast | Available | Advanced | -| has:hashtags | Available | Core | -| has:cashtags | Available | Advanced | -| has:links | Available | Core | -| has:mentions | Available | Core | -| has:media | Available | Core | -| has:images | Available | Core | -| has:videos | Available | Core | -| has:geo | Available | Advanced | -| lang: | Available | Core | -| list: | | Advanced | -| has:profile_geo | Available | | -| profile_country | Available | | -| profile_locality | Available | | -| profile_region | Available | | -| proximity | Available | | - -**Other migration resources** - -[X API migration hub](/x-api/migrate/overview) - -[Check out some sample code for these endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code "Check out some sample code for these endpoints") - -[Post counts: Enterprise to X API v2](/x-api/posts/counts/migrate/overview) - +--- +title: Overview +sidebarTitle: Overview +keywords: ["counts migration", "tweet counts migration", "v1.1 to v2 counts", "counts migration guide", "migrate counts"] + + +--- +## Comparing X API’s Post counts endpoints + +The v2 Post counts endpoint will eventually replace the [enterprise Search API’s counts endpoint](/x-api/enterprise-gnip-2.0/fundamentals/search-api#counts-requests-post-count). If you have code, apps, or tools that use an older version of a Post counts endpoint and are considering migrating to the newer X API v2 endpoints, then this guide is for you. + +## Recent Post counts comparison + +The enterprise version of the Post counts endpoints allow you to pull counts for either 30 days or from the full-archive. Therefore, the v2 recent Post counts endpoint, which looks at a 7 day time period, is not a direct replacement for either of the aforementioned endpoints. + +However, to help with comparisons, we will look at how the v2 recent Post counts endpoint compares to the enterprise 30-day endpoint. + +The following table compares the various types of recent Post counts endpoints: + +| **Description** | **Enterprise** | **X API v2** | +| :--- | :--- | :--- | +| Host domain | https://gnip-api.x.com | https://api.x.com | +| Endpoint path | /search/30day/accounts/:account_name/:label/counts.json | /2/tweets/counts/recent | +| [Authentication](/resources/fundamentals/authentication) | Basic authentication | OAuth 2.0 Bearer Token | +| Timestamp format | YYYYMMDDhhmm | YYYY-MM-DDTHH:mm:ssZ
[ISO 8601 / RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6) | +| Returns counts of Posts that are no older than | 31 days | 7 days | +| HTTP methods supported | GET | GET | +| Default request rate limits | 20 requests per 1 sec, aggregated across search data and counts requests
The per minute rate limit will vary by partner as specified in your contract. | 180 requests per 15 min per user
450 requests per 15 min per App | +| Supports filtering using [annotations](/x-api/fundamentals/post-annotations) | | ✔ | +| Supports filtering using [conversation_id](/x-api/fundamentals/conversation-id) | | ✔ | +| JSON key name for Post data array | results | data | +| Time granularity | Day, hour, or minute | Day, hour, or minute | +| Timezone | UTC | UTC | +| Request parameters for selecting time period | fromDate
toDate | start_time
end_time | +| Request parameters for navigating by Post ID | | since_id
until_id | +| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [project](/resources/fundamentals/developer-apps) | | ✔ | + +### Full-archive Post counts comparison + +The following table compares the various types of full-archive search endpoints: + +| Description | Enterprise | X API v2 | +| :--- | :--- | :--- | +| Host domain | https://gnip-api.x.com | https://api.x.com | +| Endpoint path | /search/fullarchive/accounts/:account_name/:label/counts | /2/tweets/counts/all | +| [Authentication](/resources/fundamentals/authentication) | Basic auth | OAuth 2.0 Bearer Token | +| Timestamp format | YYYYMMDDHHMM | YYYY-MM-DDTHH:mm:ssZ
[ISO 8601 / RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6) | +| Returns Post counts that are no older than | The full archive since March 2006 | The full archive since March 2006 | +| HTTP methods supported | GET
POST | GET | +| Default request rate limits | The per minute rate limit will vary by partner as specified in your contract.
20 requests per sec | 300 requests per 15 min per App
1 request per 1 sec per App | +| Granularity | Day, hour, minute | Day, hour, minute | +| Supports filtering using [annotations](/x-api/fundamentals/post-annotations) | | ✔ | +| Supports filtering using [conversation_id](/x-api/fundamentals/conversation-id) | | ✔ | +| JSON key name for Post data array | results | data | +| Request parameters for selecting time period | fromDate
toDate | start_time
end_time | +| Request parameters for navigating by Post ID | | since_id
until_id | +| JSON key name for pagination | next | meta.next_token | +| Request parameter for pagination | next_token | next_token or pagination_token | +| Timezone | UTC | UTC | +| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) that has [Academic Research access](/x-api/getting-started/about-x-api) | | ✔ | + +### Filtering operator comparison + +The two different versions (enterprise, and v2) of Post counts differ in which operators are available, and also have varying levels of operator availability within each version, which are explained below. + +Enterprise + +* There are no sub-tiers of enterprise operators. All enterprise operators are available to all enterprise users. + + + +X API v2 + +* **Core:** These operators are available to any v2 user. +* **Advanced:** These operators are only available to users that have been approved for Academic Research access. + + + +You can learn more about each of these sets of operators in their respective guides: + +* [Enterprise operators](/x-api/enterprise-gnip-2.0/fundamentals/search-api#building-search-queries) +* [X API v2 operators](/x-api/posts/search/integrate/build-a-query) + + + +Now that we understand these different operator levels within X API v2, here is the table that maps out operator availability for Post counts (note that if the cell is left blank, the operator is not available): + +| | Enterprise | v2 | +| :--- | :--- | :--- | +| keyword | Available | Core | +| emoji | Available | Core | +| “exact phrase” | Available | Core | +| # | Available | Core | +| $ | Available | Advanced | +| @ | Available | Core | +| from: | Available | Core | +| to: | Available | Core | +| url: | Available | Core | +| retweets_of: | Available | Core | +| context: | | Core | +| entity: | | Core - Only available with recent search | +| conversation_id: | | Core | +| place: | Available | Advanced | +| place_country: | Available | Advanced | +| point_radius: | Available | Advanced | +| bounding_box: | Available | Advanced | +| is:retweet | Available | Core | +| is:reply | Available | Core | +| is:quote | Available | Core | +| is:verified | Available | Core | +| -is:nullcast | Available | Advanced | +| has:hashtags | Available | Core | +| has:cashtags | Available | Advanced | +| has:links | Available | Core | +| has:mentions | Available | Core | +| has:media | Available | Core | +| has:images | Available | Core | +| has:videos | Available | Core | +| has:geo | Available | Advanced | +| lang: | Available | Core | +| list: | | Advanced | +| has:profile_geo | Available | | +| profile_country | Available | | +| profile_locality | Available | | +| profile_region | Available | | +| proximity | Available | | + +**Other migration resources** + +[X API migration hub](/x-api/migrate/overview) + +[Check out some sample code for these endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code "Check out some sample code for these endpoints") + +[Post counts: Enterprise to X API v2](/x-api/posts/counts/migrate/overview) + diff --git a/x-api/posts/create-or-edit-post.mdx b/x-api/posts/create-or-edit-post.mdx index 7c8307b1c..ae1997978 100644 --- a/x-api/posts/create-or-edit-post.mdx +++ b/x-api/posts/create-or-edit-post.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/create-post.mdx b/x-api/posts/create-post.mdx index 18d2d40de..6502c469c 100644 --- a/x-api/posts/create-post.mdx +++ b/x-api/posts/create-post.mdx @@ -1,6 +1,7 @@ --- openapi: post /2/tweets ---- + +description: Reference documentation for the endpoint and related functionality.--- Quote-posting (using the `quote_tweet_id` parameter) requires an [Enterprise plan](/enterprise-api/introduction). It is not available on self-serve (pay-per-use) tiers. diff --git a/x-api/posts/delete-post.mdx b/x-api/posts/delete-post.mdx index 0adba30c3..5521c46cf 100644 --- a/x-api/posts/delete-post.mdx +++ b/x-api/posts/delete-post.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/tweets/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/filtered-stream/integrate/matching-returned-tweets.mdx b/x-api/posts/filtered-stream/integrate/matching-returned-tweets.mdx index e53ecf17a..94c80142e 100644 --- a/x-api/posts/filtered-stream/integrate/matching-returned-tweets.mdx +++ b/x-api/posts/filtered-stream/integrate/matching-returned-tweets.mdx @@ -1,49 +1,50 @@ ---- -title: Matching Posts to Rules -sidebarTitle: Matching Posts to Rules -keywords: ["matching rules", "filter rules", "rule matching", "stream rules", "filtered stream rules", "rule tags"] ---- - -### Matching returned Posts to their associated rule - -The filtered stream endpoint gives you the ability to have multiple rules in place through a single connection. Before you start receiving Posts in your stream, you’ll need to create a rule which specifies what types of Posts you’re interested in.  - -When you specify your rules to match Posts based on a wide variety of attributes, including user attributes, geo-location, language, and many others, you can attach a tag to distinguish this rule at a higher level. Tags are a good way to contextualize your rule, especially if you have many rules in place. The filtering rules determine which Post activities will be sent through the connection. - -If you need to add a new filtering rule to capture a different type of Post, or remove an existing rule, your app can send a request to the [POST tweets/search/stream/rules](/x-api/stream/update-stream-rules) endpoint to make it happen. When that request is sent, the filtering rules are automatically modified and the changes simply take effect in the data stream with no need to reconnect. Most rule additions take effect  about 20 seconds or less. It’s unlikely, but depending on external factors (for example, network connectivity), it may take longer before you start receiving matching Posts. If you can’t find a rule in the list rule endpoint, make sure that the rule creation request succeeded; this can be done by checking your logs for any error messages. - - -#### Matching rules - -When an activity is delivered through your filtered stream connection, in a matching_rules array, it contains which list of filters matched against the Post delivered. - -In the Post payload there is additional string metadata which includes the rule id and tag that caused a specific Post to be delivered. If multiple rules match a single Post, the activity is delivered a single time with each of the matching rules included in this metadata. The matching rules provide an easy way to associate a specific Post with specific rules, which is especially helpful if you have many distinct rules. Since the data is delivered through a single stream in this manner, ensuring you have unique id and tag is essential for matching.  - -**Here is an example of how the ”matching_rules” array appears in the Post payload:** -  - -```"matching_rules": [ - { - "id": "1166916266197536768", - "tag": "test-rule-tag-00000" - }, - { - "id": "1166916266197536769", - "tag": "test-rule-tag-12345" - } - ] -``` - - -#### Rule tags - -At the time they are created, each filtering rule may be created with a tag. Rule tags have no special meaning as they are simply treated as opaque strings carried along with a rule. They will be included in the matching_rules metadata in activities returned, and are aimed at making distinguishing your rules easier at a higher level.  - -Tags provide an easy way to create logical groupings of filtering rules. For example, you may generate a unique ID for a specific rule as its tag, and allow your app to reference that ID within activities it processes to associate a result with specific customers, campaigns, categories, or other related groups. - -Note that tags cannot be updated on an existing rule and can only be included when a rule is created. In order to “update” or “rename” a tag, you need to first delete the rule, then add it again with the desired tag. The best solution is to simply use a unique identifier as your tag, which your system can associate with various other data points within your own app, all without having to change anything in the rule set. - -### Filtered stream - Recovery and redundancy features - -Note:These recovery and redundancy features are only available to those that have Enterprise access. +--- +title: Matching Posts to Rules +sidebarTitle: Matching Posts to Rules +keywords: ["matching rules", "filter rules", "rule matching", "stream rules", "filtered stream rules", "rule tags"] + +description: The filtered stream endpoint gives you the ability to have multiple rules in place through a single connection. Before you start receiving Posts in your...--- + +### Matching returned Posts to their associated rule + +The filtered stream endpoint gives you the ability to have multiple rules in place through a single connection. Before you start receiving Posts in your stream, you’ll need to create a rule which specifies what types of Posts you’re interested in.  + +When you specify your rules to match Posts based on a wide variety of attributes, including user attributes, geo-location, language, and many others, you can attach a tag to distinguish this rule at a higher level. Tags are a good way to contextualize your rule, especially if you have many rules in place. The filtering rules determine which Post activities will be sent through the connection. + +If you need to add a new filtering rule to capture a different type of Post, or remove an existing rule, your app can send a request to the [POST tweets/search/stream/rules](/x-api/stream/update-stream-rules) endpoint to make it happen. When that request is sent, the filtering rules are automatically modified and the changes simply take effect in the data stream with no need to reconnect. Most rule additions take effect  about 20 seconds or less. It’s unlikely, but depending on external factors (for example, network connectivity), it may take longer before you start receiving matching Posts. If you can’t find a rule in the list rule endpoint, make sure that the rule creation request succeeded; this can be done by checking your logs for any error messages. + + +#### Matching rules + +When an activity is delivered through your filtered stream connection, in a matching_rules array, it contains which list of filters matched against the Post delivered. + +In the Post payload there is additional string metadata which includes the rule id and tag that caused a specific Post to be delivered. If multiple rules match a single Post, the activity is delivered a single time with each of the matching rules included in this metadata. The matching rules provide an easy way to associate a specific Post with specific rules, which is especially helpful if you have many distinct rules. Since the data is delivered through a single stream in this manner, ensuring you have unique id and tag is essential for matching.  + +**Here is an example of how the ”matching_rules” array appears in the Post payload:** +  + +```"matching_rules": [ + { + "id": "1166916266197536768", + "tag": "test-rule-tag-00000" + }, + { + "id": "1166916266197536769", + "tag": "test-rule-tag-12345" + } + ] +``` + + +#### Rule tags + +At the time they are created, each filtering rule may be created with a tag. Rule tags have no special meaning as they are simply treated as opaque strings carried along with a rule. They will be included in the matching_rules metadata in activities returned, and are aimed at making distinguishing your rules easier at a higher level.  + +Tags provide an easy way to create logical groupings of filtering rules. For example, you may generate a unique ID for a specific rule as its tag, and allow your app to reference that ID within activities it processes to associate a result with specific customers, campaigns, categories, or other related groups. + +Note that tags cannot be updated on an existing rule and can only be included when a rule is created. In order to “update” or “rename” a tag, you need to first delete the rule, then add it again with the desired tag. The best solution is to simply use a unique identifier as your tag, which your system can associate with various other data points within your own app, all without having to change anything in the rule set. + +### Filtered stream - Recovery and redundancy features + +Note:These recovery and redundancy features are only available to those that have Enterprise access. \ No newline at end of file diff --git a/x-api/posts/filtered-stream/migrate/overview.mdx b/x-api/posts/filtered-stream/migrate/overview.mdx index 110d58acf..ade7b4461 100644 --- a/x-api/posts/filtered-stream/migrate/overview.mdx +++ b/x-api/posts/filtered-stream/migrate/overview.mdx @@ -1,39 +1,39 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["filtered stream migration", "stream migration", "v1.1 to v2 filtered stream", "filtered stream migration guide", "migrate filtered stream"] ---- - -## Comparing X API's filtered stream endpoints - -The v2 filtered stream endpoints group is replacing the [standard v1.1 statuses/filter](https://developer.x.com/en/docs/x-api/v1/tweets/filter-realtime/api-reference/post-statuses-filter) and [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api). If you have code, apps, or tools that use an older version of the filtered stream endpoint, and are considering migrating to the newer X API v2 endpoint, then this comparison can help you get started. - -See our more in depth migration guides for: - -[Migrating from Standard v1.1 compared to X API v2](x-api/posts/filtered-stream#standard-v1-1-compared-to-x-api-v2) - -[Migrating from PowerTrack API migration to X API v2](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-operators) - -The following table compares the filtered streaming endpoints X offers: - - -| **Description** | **Standard v1.1** | **PowerTrack API** | **X API v2** | -| :--- | :--- | :--- | :--- | -| Access | X App | Requires an enterprise contract and account | Requires a developer account ([sign up](https://developer.x.com/en/portal/petition/essential/basic-info)), and [X App](/resources/fundamentals/developer-apps) within a [Project](/resources/fundamentals/developer-apps) | -| :--- | :--- | :--- | :--- | -| Host domain | ******https://stream.x.com****** | ******https://gnip-stream.x.com****** | ******https://api.x.com****** | -| Endpoint path | ******1.1/statuses/filter.json****** | ******/stream/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json******

******/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json ******

******/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}/validation.json****** | ******/2/tweets/search/stream******

******/2/tweets/search/stream/rules****** | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | HTTP Basic Authentication | OAuth 2.0 App-Only | -| HTTP methods supported | POST | GET
POST | GET
POST | -| Required parameters | Rule defined on connection as parameter, at least one of:

* ******follow******
* ******track******
* ******locations****** | No required parameters for streaming connection, optional backfill parameter.

Rules managed separately | No required parameters for streaming connection, optional parameters to define response format and add [backfill recovery feature](/x-api/fundamentals/recovery-and-redundancy) for Academic Research access.

Rules managed separately | -| Delivery type | Streaming | Streaming

REST (for rules management) | Streaming

REST (for rules management) | -| Default request rate limits | 5 connection attempts per 5 min | 60 requests per min aggregated for both POST and GET requests

/rules: 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | Depends on the endpoint. See [rate limits](/x-api/fundamentals/rate-limits) for current limits. | -| Maximum allowed connections | 2 concurrent per authorized user | Supports multiple/redundant connections, determined by contract | Pay-per-use: 1 | -| [Recovery and redundancy features](/x-api/fundamentals/recovery-and-redundancy) | None | Backfill, redundant connections, and the Replay API | | -| Keep-alive signal/heartbeats | blank lines (\\r\\n or similar) at least every 20 seconds | blank lines (\\r\\n or similar) every 10 seconds | blank lines (\\r\\n or similar) at least every 20 seconds | -| Latency | 10 seconds | 2 seconds

At least 10 seconds for URL unwinding enrichment | 10 seconds | -| Maximum allowed rules | 1 rule (within the endpoint connection request) | Determined by contract up to 250,000 | Pay-per-use: 1,000 rules | -| Rule filter limitations | One query per connection, up to either:

\- 400 track keywords

\- 5000 follow user IDs

\- 25 location boxes | Up to 2,048 characters per rule | Pay-per-use: 1,024 characters per rule | -| [Post JSON format](/x-api/fundamentals/data-dictionary) | Standard v1.1 format | [Native Enriched](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-tweet-object) or [Activity Streams]() (selected within the [console](/x-api/enterprise-gnip-2.0/fundamentals/overview)) | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by ******fields****** and ******expansions****** request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). We will be releasing additional data format migration guides for Native Enriched and Activity Streams soon. | -| Provides Post edit history and metadata | ✔ | ✔ | ✔ | +--- +title: Overview +sidebarTitle: Overview +keywords: ["filtered stream migration", "stream migration", "v1.1 to v2 filtered stream", "filtered stream migration guide", "migrate filtered stream"] + + +## Comparing X API's filtered stream endpoints + +The v2 filtered stream endpoints group is replacing the [standard v1.1 statuses/filter](https://developer.x.com/en/docs/x-api/v1/tweets/filter-realtime/api-reference/post-statuses-filter) and [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api). If you have code, apps, or tools that use an older version of the filtered stream endpoint, and are considering migrating to the newer X API v2 endpoint, then this comparison can help you get started. + +See our more in depth migration guides for: + +[Migrating from Standard v1.1 compared to X API v2](x-api/posts/filtered-stream#standard-v1-1-compared-to-x-api-v2) + +[Migrating from PowerTrack API migration to X API v2](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-operators) + +The following table compares the filtered streaming endpoints X offers: + + +| **Description** | **Standard v1.1** | **PowerTrack API** | **X API v2** | +| :--- | :--- | :--- | :--- | +| Access | X App | Requires an enterprise contract and account | Requires a developer account ([sign up](https://developer.x.com/en/portal/petition/essential/basic-info)), and [X App](/resources/fundamentals/developer-apps) within a [Project](/resources/fundamentals/developer-apps) | +| :--- | :--- | :--- | :--- | +| Host domain | ******https://stream.x.com****** | ******https://gnip-stream.x.com****** | ******https://api.x.com****** | +| Endpoint path | ******1.1/statuses/filter.json****** | ******/stream/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json******

******/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}.json ******

******/rules/powertrack/accounts/{gnip_account_name}/publishers/twitter/{stream_label}/validation.json****** | ******/2/tweets/search/stream******

******/2/tweets/search/stream/rules****** | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | HTTP Basic Authentication | OAuth 2.0 App-Only | +| HTTP methods supported | POST | GET
POST | GET
POST | +| Required parameters | Rule defined on connection as parameter, at least one of:

* ******follow******
* ******track******
* ******locations****** | No required parameters for streaming connection, optional backfill parameter.

Rules managed separately | No required parameters for streaming connection, optional parameters to define response format and add [backfill recovery feature](/x-api/fundamentals/recovery-and-redundancy) for Academic Research access.

Rules managed separately | +| Delivery type | Streaming | Streaming

REST (for rules management) | Streaming

REST (for rules management) | +| Default request rate limits | 5 connection attempts per 5 min | 60 requests per min aggregated for both POST and GET requests

/rules: 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). | Depends on the endpoint. See [rate limits](/x-api/fundamentals/rate-limits) for current limits. | +| Maximum allowed connections | 2 concurrent per authorized user | Supports multiple/redundant connections, determined by contract | Pay-per-use: 1 | +| [Recovery and redundancy features](/x-api/fundamentals/recovery-and-redundancy) | None | Backfill, redundant connections, and the Replay API | | +| Keep-alive signal/heartbeats | blank lines (\\r\\n or similar) at least every 20 seconds | blank lines (\\r\\n or similar) every 10 seconds | blank lines (\\r\\n or similar) at least every 20 seconds | +| Latency | 10 seconds | 2 seconds

At least 10 seconds for URL unwinding enrichment | 10 seconds | +| Maximum allowed rules | 1 rule (within the endpoint connection request) | Determined by contract up to 250,000 | Pay-per-use: 1,000 rules | +| Rule filter limitations | One query per connection, up to either:

\- 400 track keywords

\- 5000 follow user IDs

\- 25 location boxes | Up to 2,048 characters per rule | Pay-per-use: 1,024 characters per rule | +| [Post JSON format](/x-api/fundamentals/data-dictionary) | Standard v1.1 format | [Native Enriched](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-tweet-object) or [Activity Streams]() (selected within the [console](/x-api/enterprise-gnip-2.0/fundamentals/overview)) | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by ******fields****** and ******expansions****** request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). We will be releasing additional data format migration guides for Native Enriched and Activity Streams soon. | +| Provides Post edit history and metadata | ✔ | ✔ | ✔ | | Unique Features | Filtering done via query parameters on connection request

No configuration UI | Filtering done via rules created through an independent endpoint

[Enrichment](/x-api/enterprise-gnip-2.0/enterprise-gnip#enrichments) features available in contract

Configuration on console.gnip.com UI | Filtering done via [rules](/x-api/posts/filtered-stream/integrate/build-a-rule) created through an independent endpoint

[Metrics](/x-api/fundamentals/metrics) and URL enrichment features included

Object [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) specified with request parameters

Post [Annotations](/x-api/fundamentals/post-annotations)

[Conversation ID](/x-api/fundamentals/conversation-id) operator and field

Configuration through [Developer Console](/resources/fundamentals/developer-portal) | \ No newline at end of file diff --git a/x-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.mdx b/x-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.mdx index e7e32485c..e8424bb28 100644 --- a/x-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.mdx +++ b/x-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.mdx @@ -1,176 +1,40 @@ ---- -title: v1 to v2 (Enterprise) -sidebarTitle: v1 to v2 (Enterprise) -keywords: ["PowerTrack migration", "enterprise to v2 filtered stream", "PowerTrack to v2", "enterprise stream migration", "migrate PowerTrack", "v1 to v2 enterprise stream"] ---- - -### PowerTrack API migration to X API v2 filtered stream - -Use this migration guide to understand the similarities and differences between [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api) and X API v2 [filtered stream](/x-api/posts/filtered-stream), and to help migrate a current PowerTrack API integration to v2 filtered stream. - -* **Similarities** - * Streaming delivery method - * Integration process - * Persistent stream connection with separate rules management endpoints - * Rule syntax - * Rule operators (with exceptions) - * Rule matching logic - * Support for Post edit history and metadata -* **Differences** - * Rule length - * Rule volume - * Endpoint URLs - * App and Project requirement for access - * Authentication method - * Request parameters - * Usage tracking - * Multiple streams, redundant conections, backfill and Replay recovery - * Request parameters and response format - * Response JSON data structure - -#### Similarities - -**Streaming delivery method** - -Both PowerTrack and X API v2 filtered stream use streaming data delivery, which require the client to establish an open connection to an endpoint and keeping a very long lived HTTP request, and parsing the response incrementally from the server in real time.  Both PowerTrack and X API v2 filtered stream filter publicly available Posts matching rules that exist on the stream in real time, and use keep-alive signals as new line characters (\\r\\n) to signal the connection is still active. Both PowerTrack and X API v2 filtered stream endpoint connections deliver data in real time and should be read by the connecting client quickly.   - -**Integration process** - -Integrating with filtered stream is similar to integrating with PowerTrack, using the general process below: - -1. Establish a streaming connection. -2. Asynchronously send separate requests to add and delete rules from the stream. -3. Reconnect to the stream automatically when connection is disconnected. - -**Persistent stream connection with separate rules management endpoints** - -Similar to the PowerTrack API and Rules API, the new X API v2 filtered stream endpoints allows you to apply multiple rules to a single stream and add and remove rules to your stream while maintaining the stream connection. - -| | | | -| :--- | :--- | :--- | -| **Feature** | **PowerTrack API** | **X API v2 filtered stream** | -| **Connection endpoint** | GET /stream | [GET /2/tweets/search/stream](/x-api/stream/stream-filtered-posts) | -| **Add rules** | POST /rules | [POST /2/tweets/search/stream/rules](/x-api/stream/update-stream-rules) | -| **Get rules** | GET /rules | [GET /2/tweets/search/stream/rules](/x-api/stream/get-stream-rules) | -| **Delete rules** | POST /rules_method=delete | [POST /2/tweets/search/stream/rules](/x-api/stream/update-stream-rules) | - -**Rule syntax, operators, and matching rules logic** - -The X API v2 filtered stream uses a subset of the same rule operators currently used for PowerTrack rules. These operators are used to create boolean based rule syntax used for filtering desired matching Posts from the live stream.  Both PowerTrack and filtered stream use the same rule syntax for building rules and matching logic is the same. While the majority of the operators are available for both PowerTrack and filter stream, there are a few notable differences and net new operators listed below.  For more details and example uses for each operator see current [PowerTrack operators](/x-api/enterprise-gnip-2.0/powertrack-api#powertrack-operators) and current X API v2 [filtered stream operators](/x-api/posts/filtered-stream/integrate/operators).  - -Please note that many operators (noted as 'advanced operators') are reserved for those users who have been approved for [Academic Research access or Enterprise access](/x-api/getting-started/about-x-api). - -Operators available with both PowerTrack and X API v2 Filtered stream: - -| **Standalone operators** | **Conjunction required operators (must be used with at least one standalone operator within a rule)** | -| :--- | :--- | -| keyword (example: coffee )

emoji (example: 🐶 or \\uD83D\\uDC36 )

"exact phrase match" (example: "happy birthday" )

from:

to:

@

retweets_of:

#

url: | has:links

lang:

has:mentions

has:media

has:images

has:videos

is:retweet

is:quote

is:verified

has:hashtags

has:geo

sample:

-is:nullcast | - -| | -| :--- | -| **Net new operators available with X API v2 filtered stream** | -| conversation_id: \- matches on Posts that exist in any reply threads from the specified Post conversation root.Net new operators available with X API v2 filtered stream:

context: \- matches on Posts that have been annotated with a context of interest. 

entity: \- matches on Posts that have been annotated with an entity of interest. | - -| | -| :--- | -| **Operators currently only available on PowerTrack API** | -| url_title:

url_description:

followers_count:

statuses_count:

friends_count:

listed_count:

"proximity match"~3

contains:

has:symbols

url_contains:

in\_reply\_to\_status\_id:

retweets\_of\_status_id:

source:

bio:

bio_name:

bio_location:

place:

place_country:

point_radius:

bounding_box:

is:reply

(Available without conjunction)

has:links

lang:

has:mentions

has:media

has:images

has:videos

is:retweet

is:quote

is:verified

is:reply

has:hashtags

has:geo

sample: | - -**Support for Post edit history and metadata** - -Both versions provide metadata that describes any edit history. Check out the [filtered stream API References](/x-api/posts/filtered-stream/introduction) and the [Edit Posts fundamentals page](/x-api/fundamentals/edit-posts) for more details.  - -#### Differences - -**Rule length** - -Rule length is measured the same way (by character count) for both PowerTrack and filtered stream rules, however the maximum length for PowerTrack rules is 2048 characters and the maximum rule length for rules on X API v2 filtered stream varies by [access level](/x-api/getting-started/about-x-api).  - -Enterprise access -  2048 characters (please contact your designated account manager regarding your specific account) - -**Rule volume** - -The PowerTrack maximum rule volume per stream is defined within the enterprise account contract.  X API v2 filtered stream rule volume varies by [access level](/x-api/getting-started/about-x-api). - -Enterprise access - 25000+ rules (please contact your designated account manager regarding your specific account) -  - -**Endpoint URLs** - -* PowerTrack endpoints: - * https://gnip-stream.x.com/stream/powertrack/accounts/{account\_name}/publishers/twitter/{stream\_label}.json - * https://gnip-api.x.com/rules/powertrack/accounts/{account\_name}/publishers/twitter/{stream\_label}.json - * https://gnip-api.x.com/rules/powertrack/accounts/{account\_name}/publishers/twitter/{stream\_label}/validation.json -* X API v2 endpoint: - * https://api.x.com/2/tweets/search/stream - * https://api.x.com/2/tweets/search/stream/rule - -**App and Project requirements for v2 access** - -PowerTrack access is granted through a contracted annual subscription for data, and set up through console.gnip.com by your account manager at X.  PowerTrack does not require a X developer App to access.  In order to use the X API v2 filter stream, you must have [signed up for a X developer account](https://developer.x.com/en/portal/petition/essential/basic-info), and a X [developer App](https://developer.x.com/en/portal/projects-and-apps.html) associated with an App. The developer App and Project setup for X API v2 access is all done through the [Developer Console](https://developer.x.com/en/portal/projects-and-apps).   - -**Authentication method** - -The PowerTrack API endpoints use Basic Authentication set up in console.gnip.com. The X API v2 filtered stream endpoints require a X developer App and an [OAuth 2.0 App Access Token](/resources/fundamentals/authentication#oauth-2-0) (also referred to as Application-only or Bearer Authentication). To make requests to the X API v2 version you must use your specific developer App's Access Token to authenticate your requests. - -In the process of setting up your developer account, developer App and Project, an App Access Token is created and shared within the dev portal user interface, however, you can generate a new one by navigating to your app's “Keys and tokens” page on the [Developer Console](https://developer.x.com/en/portal/projects-and-apps). If you’d like to generate/destroy the App Access Tokens programmatically, see this [OAuth 2.0 App-Only guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -**Usage tracking** - -PowerTrack usage can be retrieved programatically using the Usage API, or can be seen in console.gnip.com on the [usage tab](/x-api/enterprise-gnip-2.0/fundamentals/overview#usage-tab).  Post consumption across all PowerTrack streams is deduplicated each day and volume consumption is defined within the enterprise contract.  - -X API v2 filtered stream usage can be tracked within the Developer Console at the Project level. Post consumption is [set at the Project level](/resources/fundamentals/developer-apps) and is shared across several different X API v2 endpoints, including filtered stream, recent search, user Post timeline and user mention timeline.  With pay-per-use pricing, you pay for the Posts you consume. - -**Multiple streams, redundant conections, backfill and Replay API for recovery** - -There are several recovery and redunancy features available via PowerTrack, some of which are not yet available for X API v2 filtered stream.  For PowerTrack, all [recovery and redundancy features](/x-api/enterprise-gnip-2.0/powertrack-api#recovery-and-redundancy-features) are configured within the enterprise contract. PowerTrack API currently has the flexibility to offer multiple PowerTrack streams (commonly "dev" and "production") with unique rulesets.  Currently, the X API v2 filtered stream is only available with a single stream. - -PowerTrack allows you to connect to have multiple connections to a single stream, generally used for redundant connections to different data centers or clients.  - -If a PowerTrack stream is disconnected breifly, a reconnection can be made using the backfillMinutes parameter to reduce the chance of data loss within five minutes of the disconection. While we have added this functionality to the X API v2 version, it is currently only available with Academic Research access, and has been renamed to backfill_minutes. - -If a PowerTrack stream is disconnected for longer than a 5 minute period, the separate [Replay API](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) can be used to recover data for up to a 2 hour period in the recent 5 day past.  Currently, the X API v2 filtered stream does not have a replay feature. - -**Request parameters and response format** - -One of the biggest differences between PowerTrack API and X API v2 filtered stream is the parameter functionality. - -Using the X API v2 filtered stream, there are several parameters used on the connection request to identify which fields or expanded objects to return in the Post payload.  This is common for all v2 endpoints. By default, only the Post id and text are returned for matching Posts but additional parameters, fields and expansions described below, can be added in order to recieve more detailed data per matching Post.  - -fields: X API v2 endpoints enable you to select which fields are provided in your payload. For example, Post, User, Media, Place, and Poll objects all have a list of fields that can be returned (or not).  - -expansions: Used to expand the complementary objects referenced in Post JSON payloads. For example, all Retweets and Replies reference other Posts. By setting expansions=referenced_tweets.id, these other Post objects are expanded according to the \`tweet.fields\` setting.  Other objects such as users, polls, and media can be expanded. - -https://api.x.com/2/tweets/search/stream?tweet.fields=created\_at,public\_metrics,author\_id,entities&expansions=attachments.poll\_ids - -You can learn more about how to use fields and expansions by visiting our [guide](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions), and by reading through our broader [data dictionary](/x-api/fundamentals/data-dictionary). - -| | | -| :--- | :--- | -| **Connection to PowerTrack ** | **Example request to X API v2 filtered stream** | -| curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/powertrack/accounts/:account\_name/publishers/twitter/:stream\_label.json" | curl "https://api.x.com/2/tweets/search/stream?tweet.fields=attachments,author\_id,context\_annotations,conversation\_id,created\_at,entities,geo,id,in\_reply\_to\_user\_id,lang,possibly\_sensitive,public\_metrics,referenced\_tweets,reply\_settings,source,text,withheld&user.fields=created\_at,description,entities,id,location,name,pinned\_tweet\_id,profile\_image\_url,protected,public\_metrics,url,username,verified,withheld&expansions=author\_id,referenced\_tweets.id,referenced\_tweets.id.author\_id,entities.mentions.username,attachments.poll\_ids,attachments.media\_keys,in\_reply\_to\_user\_id,geo.place\_id&place.fields=contained\_within,country,country\_code,full\_name,geo,id,name,place\_type&poll.fields=duration\_minutes,end\_datetime,id,options,voting\_status" -H "Authorization: Bearer $ACCESS_TOKEN" | - -The PowerTrack API data format is set within console.gnip.com at the stream settings level, which can be set to either the X [native enriched format](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-tweet-object) or [Activity streams format]().  - -PowerTrack API only uses one optional parameter on connection, to reconnect using backfill (backfillMinutes=5). This optional parameter is also available to filtered stream, but is called backfill_minutes, and is only available via Academic Research access. -  - -https://gnip-stream.x.com/stream/powertrack/accounts/{account\_name}/publishers/twitter/{stream\_label}.json?backfillMinutes=5 - -**Response structure and data format** - -As described above, the request parameters set at the connection request for X API v2 filtered stream determine the response data returned.  There are several different response possibilites using different fields and expansions which can range from the most simple default response with only the Post id and text, to an extremely detailed and expanded data payload. - -The data format for PowerTrack is set within console.gnip.com at the stream settings level, which can be set to either the X Native Enriched format or Activity Streams format.  - -The following table references Post response examples in each different format: - -| | | | -| :--- | :--- | :--- | -| **Native enriched format** | **Activity streams format** | **X API v2 filtered stream format** | -| [Payload examples](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#native-enriched-example-payloads) | [Payload examples](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#activity-streams-payload-examples) | [Payload examples](/x-api/fundamentals/data-dictionary#twitter-api-v2-example-payloads) | - -If you would like to know more about how the enterprise data formats map to the X API v2 format, please visit our following guides: - -* [Native Enriched to X API v2 format migration guide](/x-api/migrate/data-format-migration#migrating-from-native-enriched-data-format-to-v2) -* [Activity Streams to X API v2 format migration guide](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) +--- +title: v1 to v2 (Enterprise) +sidebarTitle: v1 to v2 (Enterprise) +keywords: ["PowerTrack migration", "enterprise to v2 filtered stream", "PowerTrack to v2", "enterprise stream migration", "migrate PowerTrack", "v1 to v2 enterprise stream"] + + +--- +### PowerTrack API migration to X API v2 filtered stream + +Use this migration guide to understand the similarities and differences between [PowerTrack API](/x-api/enterprise-gnip-2.0/powertrack-api) and X API v2 [filtered stream](/x-api/posts/filtered-stream), and to help migrate a current PowerTrack API integration to v2 filtered stream. + +* **Similarities** + * Streaming delivery method + * Integration process + * Persistent stream connection with separate rules management endpoints + * Rule syntax + * Rule operators (with exceptions) + * Rule matching logic + * Support for Post edit history and metadata +* **Differences** + * Rule length + * Rule volume + * Endpoint URLs + * App and Project requirement for access + * Authentication method + * Request parameters + * Usage tracking + * Multiple streams, redundant conections, backfill and Replay recovery + * Request parameters and response format + * Response JSON data structure + +#### Similarities + +**Streaming delivery method** + +Both PowerTrack and X API v2 filtered stream use streaming data delivery, which require the client to establish an open connection to an endpoint and keeping a very long lived HTTP request, and parsing the response incrementally from the server in real time.  Both PowerTrack and X API v2 filtered stream filter publicly available Posts matching rules that exist on the stream in real time, and use keep-alive signals as new line characters (\\r\\n) to signal the connection is still active. Both PowerTrack and X API v2 filtered stream endpoint connections deliver data in real time and should be read by the connecting client quickly.   + +**Integration process** + +Integrating with filtered stream is similar to integrating with P \ No newline at end of file diff --git a/x-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx b/x-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx index 169cc808f..33db29d59 100644 --- a/x-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx @@ -1,238 +1,137 @@ ---- -title: v1 to v2 -sidebarTitle: v1 to v2 -keywords: ["v1.1 to v2 migration", "filtered stream migration", "migrate filtered stream", "standard to v2 filtered stream", "v1 to v2 filtered stream", "migration guide"] ---- - -### Standard v1.1 compared to X API v2 - -If you have been working with the v1.1 [statuses/filter](https://developer.x.com/en/docs/x-api/v1/tweets/filter-realtime/api-reference/post-statuses-filter) endpoint, this guide can help you understand the similarities and differences between the standard and X API v2 filtered stream endpoints. - -* **Similarities** - * Request parameters and operators - * Support for Post edit history and metadata -* **Differences** - * Endpoint URLs - * App and Project requirement - * Authentication method - * Rule volume and persistent stream - * Response data format - * Request parameters - * Availability of recovery and redundancy features - * Query operators - -#### Similarities - -**Request parameters and operators** - -The standard v1.1 statuses/filter endpoint features a few parameters that can be passed along with the request to filter the stream. With v2 filtered stream, you instead use a set of [operators](/x-api/posts/filtered-stream/integrate/operators) that can be connected together using boolean logic to filter for desired Posts. The available operators include some that are direct replacements for the existing standard v1.1 parameters.  - -The following standard v1.1 request parameters have equivalent operators in X API v2: -  - -| **Standard** | **X API v2** | -| :--- | :--- | -| follow \- A comma-separated list of user IDs, indicating the users whose Posts should be delivered on the stream. | Many operators that can help you find Posts related to specific users:

* @
* from:
* to:
* etc. | -| track \- A comma-separated list of phrases which will be used to determine what Posts will be delivered on the stream. | Many operators that can help you find Posts related to specific keywords:

* keyword
* "exact phrase match"
* #
* etc. | - -**Support for Post edit history and metadata** - -Both versions provide metadata that describes any edit history. Check out the [filtered stream API References](/x-api/posts/filtered-stream/introduction) and the [Post edits fundamentals page](/x-api/fundamentals/edit-posts) for more details.  - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * https://stream.x.com/1.1/statuses/filter.json -* X API v2 endpoint: - * https://api.x.com/2/tweets/search/stream - * https://api.x.com/2/tweets/search/stream/rule - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. - -**Authentication method** - -The standard endpoint supports [OAuth 1.0a User Context](/resources/fundamentals/authentication), whereas the X API v2 filtered stream endpoints supports [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) (also referred to as Application-only authentication). To make requests to the X API v2 version you must use a App Access Token to authenticate your requests. - -If you no longer have the App Access Token that was presented to you when you created your App and app in the Developer Console, you can generate a new one by navigating to your app's “Keys and tokens” page on the Developer Console. If you’d like to generate an App Access Token programmatically, see this [OAuth 2.0 App-Only guide](/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token).  - -**Rule volume and persistent stream** - -The standard v1.1 endpoint supports a single rule to filter the streaming connection. To change the rule, you have to disconnect the stream and submit a new request with the revised filtering rules submitted as parameters.  - -The X API v2 filtered stream endpoint allows you to apply multiple rules to a single stream and add and remove rules to your stream while maintaining the stream connection.  - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you wil need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any Post fields that you request from these endpoints will return in the primary Post object. Any expanded user, media, poll, or place objects and fields will return in an includes object within your response. You can then match any expanded objects back to the Post object by matching the IDs located in both the Post and the expanded object.  - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.  -   - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - -**Request parameters** - -There are also a set of standard filtered stream request parameters **not** supported in X API v2: - -| Standard v1.1 parameter | Details | -| :--- | :--- | -| locations \- A comma-separated list of longitude,latitude pairs specifying a set of bounding boxes to filter Posts by. | We have not released location-based operators for X API v2 yet. | -| Delimited | With the v1.1 endpoint, setting this to the string length indicates that statuses should be delimited in the stream, so that clients know how many bytes to read before the end of the status message.

This functionality is not available with X API v2. | -| Stall_warnings | With the v1.1 endpoint, setting this parameter to true will cause periodic messages to be delivered if the client is in danger of being disconnected. 

With X API v2, stall warnings are sent by default with the new line sent every so often. | - -**Availability of recovery and redundancy features** - -The X API v2 version of filtered stream introduces recovery and redundancy features that can help you maximize streaming up-time as well as recover any Posts that might have been missed due to a disconnection that lasted five minutes or less. - -Redundant connections allows you to connect to a given stream up to two times, which can help ensure that you maintain a connection to the stream at all times, even if one of your connections fails.  - -The backfill_minutes parameter can be used to recover up to five minutes of missed data.  - -Both of these features are only available via [Academic Research access](/x-api/getting-started/about-x-api). You can learn more about this functionality via our [recovery and redundancy features](/x-api/fundamentals/recovery-and-redundancy) integration guide.  - -**New query operators** - -X API v2 introduces new operators in support of two new features:  - -* **[Conversation IDs](/x-api/fundamentals/conversation-id)** \- As conversations unfold on X, a conservation ID will be available to mark Posts that are part of the conversation. All Posts in the conversation will have their conversation_id set to the Post ID that started it.  - * conversation_id: -* **[X Annotations](/x-api/fundamentals/post-annotations)** provide contextual information about Posts, and include entity and context annotations. Entities are comprised of people, places, products and organizations. Contexts are domains, or topics, that surfaced entities are a part of. For example, people mentioned in a Post may have a context that indicates whether they are an athlete, actor, or politician. - * context: \- matches on Posts that have been annotated with a context of interest. - * entity: \- matches on Posts that have been annotated with an entity of interest. - ---- - -## Code examples - -### Add a rule to filtered stream (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \ - -H "Authorization: Bearer $BEARER_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"add": [{"value": "cat has:images", "tag": "cats with images"}]}' -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/search/stream/rules" - -headers = { - "Authorization": f"Bearer {bearer_token}", - "Content-Type": "application/json" -} - -data = { - "add": [{"value": "cat has:images", "tag": "cats with images"}] -} - -response = requests.post(url, headers=headers, json=data) -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Add a rule to filtered stream -response = client.posts.add_stream_rules( - add=[{"value": "cat has:images", "tag": "cats with images"}] -) -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Add a rule to filtered stream -const response = await client.posts.addStreamRules({ - add: [{ value: "cat has:images", tag: "cats with images" }], -}); -console.log(response.data); -``` - - - -### Connect to filtered stream (v2) - - - -```bash cURL -curl "https://api.x.com/2/tweets/search/stream?tweet.fields=created_at,author_id" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/search/stream" - -params = {"tweet.fields": "created_at,author_id"} -headers = {"Authorization": f"Bearer {bearer_token}"} - -# Stream Posts in real-time -response = requests.get(url, headers=headers, params=params, stream=True) -for line in response.iter_lines(): - if line: - print(line.decode("utf-8")) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Connect to filtered stream -for post in client.posts.stream( - tweet_fields=["created_at", "author_id"] -): - print(f"{post.data.created_at}: {post.data.text[:50]}...") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Connect to filtered stream -const stream = client.posts.stream({ - tweetFields: ["created_at", "author_id"], -}); - -for await (const post of stream) { - console.log(`${post.data?.created_at}: ${post.data?.text?.slice(0, 50)}...`); -} -``` - - +--- +title: v1 to v2 +sidebarTitle: v1 to v2 +keywords: ["v1.1 to v2 migration", "filtered stream migration", "migrate filtered stream", "standard to v2 filtered stream", "v1 to v2 filtered stream", "migration guide"] + + +--- + +### Standard v1.1 compared to X API v2 + +If you have been working with the v1.1 [statuses/filter](https://developer.x.com/en/docs/x-api/v1/tweets/filter-realtime/api-reference/post-statuses-filter) endpoint, this guide can help you understand the similarities and differences between the standard and X API v2 filtered stream endpoints. + +* **Similarities** + * Request parameters and operators + * Support for Post edit history and metadata +* **Differences** + * Endpoint URLs + * App and Project requirement + * Authentication method + * Rule volume and persistent stream + * Response data format + * Request parameters + * Availability of recovery and redundancy features + * Query operators + +#### Similarities + +**Request parameters and operators** + +The standard v1.1 statuses/filter endpoint features a few parameters that can be passed along with the request to filter the stream. With v2 filtered stream, you instead use a set of [operators](/x-api/posts/filtered-stream/integrate/operators) that can be connected together using boolean logic to filter for desired Posts. The available operators include some that are direct replacements for the existing standard v1.1 parameters.  + +The following standard v1.1 request parameters have equivalent operators in X API v2: +  + +| **Standard** | **X API v2** | +| :--- | :--- | +| follow \- A comma-separated list of user IDs, indicating the users whose Posts should be delivered on the stream. | Many operators that can help you find Posts related to specific users:

* @
* from:
* to:
* etc. | +| track \- A comma-separated list of phrases which will be used to determine what Posts will be delivered on the stream. | Many operators that can help you find Posts related to specific keywords:

* keyword
* "exact phrase match"
* #
* etc. | + +**Support for Post edit history and metadata** + +Both versions provide metadata that describes any edit history. Check out the [filtered stream API References](/x-api/posts/filtered-stream/introduction) and the [Post edits fundamentals page](/x-api/fundamentals/edit-posts) for more details.  + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * https://stream.x.com/1.1/statuses/filter.json +* X API v2 endpoint: + * https://api.x.com/2/tweets/search/stream + * https://api.x.com/2/tweets/search/stream/rule + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. + +**Authentication method** + +The standard endpoint supports [OAuth 1.0a User Context](/resources/fundamentals/authentication), whereas the X API v2 filtered stream endpoints supports [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) (also referred to as Application-only authentication). To make requests to the X API v2 version you must use a App Access Token to authenticate your requests. + +If you no longer have the App Access Token that was presented to you when you created your App and app in the Developer Console, you can generate a new one by navigating to your app's “Keys and tokens” page on the Developer Console. If you’d like to generate an App Access Token programmatically, see this [OAuth 2.0 App-Only guide](/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token).  + +**Rule volume and persistent stream** + +The standard v1.1 endpoint supports a single rule to filter the streaming connection. To change the rule, you have to disconnect the stream and submit a new request with the revised filtering rules submitted as parameters.  + +The X API v2 filtered stream endpoint allows you to apply multiple rules to a single stream and add and remove rules to your stream while maintaining the stream connection.  + +**Response data format** + +One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. + +For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. + +The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you wil need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any Post fields that you request from these endpoints will return in the primary Post object. Any expanded user, media, poll, or place objects and fields will return in an includes object within your response. You can then match any expanded objects back to the Post object by matching the IDs located in both the Post and the expanded object.  + +We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  + +We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  +  + +In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and [user](/x-api/fundamentals/data-dictionary#user) objects. + +* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  +* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  +* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  +* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.  +   + +We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: + +* A [conversation_id](/x-api/fundamentals/conversation-id) field +* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities +* Several new [metrics](/x-api/fundamentals/metrics) fields  +* A new reply_setting field, which shows you who can reply to a given Post + +**Request parameters** + +There are also a set of standard filtered stream request parameters **not** supported in X API v2: + +| Standard v1.1 parameter | Details | +| :--- | :--- | +| locations \- A comma-separated list of longitude,latitude pairs specifying a set of bounding boxes to filter Posts by. | We have not released location-based operators for X API v2 yet. | +| Delimited | With the v1.1 endpoint, setting this to the string length indicates that statuses should be delimited in the stream, so that clients know how many bytes to read before the end of the status message.

This functionality is not available with X API v2. | +| Stall_warnings | With the v1.1 endpoint, setting this parameter to true will cause periodic messages to be delivered if the client is in danger of being disconnected. 

With X API v2, stall warnings are sent by default with the new line sent every so often. | + +**Availability of recovery and redundancy features** + +The X API v2 version of filtered stream introduces recovery and redundancy features that can help you maximize streaming up-time as well as recover any Posts that might have been missed due to a disconnection that lasted five minutes or less. + +Redundant connections allows you to connect to a given stream up to two times, which can help ensure that you maintain a connection to the stream at all times, even if one of your connections fails.  + +The backfill_minutes parameter can be used to recover up to five minutes of missed data.  + +Both of these features are only available via [Academic Research access](/x-api/getting-started/about-x-api). You can learn more about this functionality via our [recovery and redundancy features](/x-api/fundamentals/recovery-and-redundancy) integration guide.  + +**New query operators** + +X API v2 introduces new operators in support of two new features:  + +* **[Conversation IDs](/x-api/fundamentals/conversation-id)** \- As conversations unfold on X, a conservation ID will be available to mark Posts that are part of the conversation. All Posts in the conversation will have their conversation_id set to the Post ID that started it.  + * conversation_id: +* **[X Annotations](/x-api/fundamentals/post-annotations)** provide contextual information about Posts, and include entity and context annotations. Entities are comprised of people, places, products and organizations. Contexts are domains, or topics, that surfaced entities are a part of. For example, people mentioned in a Post may have a context that indicates whether they are an athlete, actor, or politician. + * context: \- matches on Posts that have been annotated with a context of interest. + * entity: \- matches on Posts that have been annotated with an entity of interest. + +--- + +## Code examples + +### Add a rule to filtered stream (v2) + + +**Standard v1.1 vs v2 examples** + +See the full migration examples in the official X API documentation. diff --git a/x-api/posts/get-28-hour-post-insights.mdx b/x-api/posts/get-28-hour-post-insights.mdx index a623f2727..66673bb15 100644 --- a/x-api/posts/get-28-hour-post-insights.mdx +++ b/x-api/posts/get-28-hour-post-insights.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/insights/28hr ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-count-of-all-posts.mdx b/x-api/posts/get-count-of-all-posts.mdx index 42cd08fc1..0fb250883 100644 --- a/x-api/posts/get-count-of-all-posts.mdx +++ b/x-api/posts/get-count-of-all-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/counts/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-count-of-recent-posts.mdx b/x-api/posts/get-count-of-recent-posts.mdx index 464df2be6..77c6b03eb 100644 --- a/x-api/posts/get-count-of-recent-posts.mdx +++ b/x-api/posts/get-count-of-recent-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/counts/recent ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-historical-post-insights.mdx b/x-api/posts/get-historical-post-insights.mdx index 7cc69f98b..f0e90b6c0 100644 --- a/x-api/posts/get-historical-post-insights.mdx +++ b/x-api/posts/get-historical-post-insights.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/insights/historical ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-liking-users.mdx b/x-api/posts/get-liking-users.mdx index 2c577cbcc..6a319905e 100644 --- a/x-api/posts/get-liking-users.mdx +++ b/x-api/posts/get-liking-users.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id}/liking_users ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-post-analytics.mdx b/x-api/posts/get-post-analytics.mdx index 961c610c4..ddb2ce5e3 100644 --- a/x-api/posts/get-post-analytics.mdx +++ b/x-api/posts/get-post-analytics.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/analytics ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-post-by-id.mdx b/x-api/posts/get-post-by-id.mdx index 00c223ada..580dbeb89 100644 --- a/x-api/posts/get-post-by-id.mdx +++ b/x-api/posts/get-post-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-posts-by-ids.mdx b/x-api/posts/get-posts-by-ids.mdx index 87436913f..efb9a70ad 100644 --- a/x-api/posts/get-posts-by-ids.mdx +++ b/x-api/posts/get-posts-by-ids.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-quoted-posts.mdx b/x-api/posts/get-quoted-posts.mdx index 57df7fd8a..13a425945 100644 --- a/x-api/posts/get-quoted-posts.mdx +++ b/x-api/posts/get-quoted-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id}/quote_tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-reposted-by.mdx b/x-api/posts/get-reposted-by.mdx index a50f659af..968f17876 100644 --- a/x-api/posts/get-reposted-by.mdx +++ b/x-api/posts/get-reposted-by.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id}/retweeted_by ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/get-reposts.mdx b/x-api/posts/get-reposts.mdx index 71026dcaa..dbd83fe84 100644 --- a/x-api/posts/get-reposts.mdx +++ b/x-api/posts/get-reposts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/{id}/retweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/hide-replies/apps.mdx b/x-api/posts/hide-replies/apps.mdx index 4bc8bb760..c055606b8 100644 --- a/x-api/posts/hide-replies/apps.mdx +++ b/x-api/posts/hide-replies/apps.mdx @@ -1,62 +1,63 @@ ---- -title: Apps -sidebarTitle: Apps -keywords: ["hide replies apps", "reply moderation apps", "apps for hide replies", "hide replies applications", "reply moderation tools"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Apps using the hide replies endpoint - -Here's a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their technology with the X API, they created useful experiences to help all users enhance the public conversation. - - ![Clarabridge](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/hide-replies/clarabridge.jpg.twimg.1920.jpg) - -**Clarabridge** - -Clarabridge integrates hide replies so that companies can keep their X feed clean and interesting to read. Replies can be hidden manually, and agents can also use Clarabridge’s text analytics to automatically detect profanity and other language that is not in line with brand policy. - -[Go to website ▸](https://www.clarabridge.com/ "Go to website ▸") - -[Clarabridge on X](https://x.com/Clarabridge "Clarabridge on X") - - ![Perspective API template app](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/hide-replies/perspective-logo.png.twimg.1920.png) - -**Perspective API template app** - -Perspective is an artificial intelligence trained by Jigsaw (a unit within Alphabet) to detect toxic comments. This app detects a person's incoming replies, and automatically hides a reply based on the “score” that indicates how confident Perspective is that a comment is similar to toxic comments it’s seen in the past. This is an open source template app developed by X. We encourage you to personalize it to build tools for your users. - -[Use app ▸](https://quintessential-yoke.glitch.me "Use app ▸") - -[Jigsaw on X](https://x.com/jigsaw "Jigsaw on X") - - ![Reshuffle](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 150 150%22%3E%3C/svg%3E) - -**Reshuffle** - -Reshuffle is a platform to connect business applications with flexible scripts. They built an integration script to detect and hide replies that include keywords you define. To try it out, make sure you have a valid app enabled for Hide replies, then follow the instructions in the repo. - -[Go to app ▸](https://github.com/reshufflehq/reshuffle "Go to app ▸") - -[Reshuffle on X](https://x.com/reshufflehq "Reshuffle on X") - - ![Hide unwanted replies](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 396 397%22%3E%3C/svg%3E) - -**Hide unwanted replies** - -Dara Oladosu, the developer behind the popular app QuotedReplies, built an app that automatically hides replies that meet some of the criteria that he’s determined are more likely to exhibit abusive behavior, including replies that contain certain keywords he’s muted in the past. - -[Go to app ▸](https://hideunwantedreplies.com/ "Go to app ▸") - -[Dara Oladosu on X](https://x.com/dara_tobi "Dara Oladosu on X") - - ![Pandaflow](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 94 94%22%3E%3C/svg%3E) - -**Pandaflow** - -Pandaflow is a no code platform to automate workflows. They integrate the endpoint so users can programmatically hide replies based on a custom flow they define. - -[Go to app ▸](https://pandaflow.io/ "Go to app ▸") - -[Pandaflow on X](https://x.com/pandaflowio "Pandaflow on X") - +--- +title: Apps +sidebarTitle: Apps +keywords: ["hide replies apps", "reply moderation apps", "apps for hide replies", "hide replies applications", "reply moderation tools"] + +description: Here's a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their technology with the X API, they c...--- + +import { Button } from '/snippets/button.mdx'; + +## Apps using the hide replies endpoint + +Here's a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their technology with the X API, they created useful experiences to help all users enhance the public conversation. + + ![Clarabridge](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/hide-replies/clarabridge.jpg.twimg.1920.jpg) + +**Clarabridge** + +Clarabridge integrates hide replies so that companies can keep their X feed clean and interesting to read. Replies can be hidden manually, and agents can also use Clarabridge’s text analytics to automatically detect profanity and other language that is not in line with brand policy. + +[Go to website ▸](https://www.clarabridge.com/ "Go to website ▸") + +[Clarabridge on X](https://x.com/Clarabridge "Clarabridge on X") + + ![Perspective API template app](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/hide-replies/perspective-logo.png.twimg.1920.png) + +**Perspective API template app** + +Perspective is an artificial intelligence trained by Jigsaw (a unit within Alphabet) to detect toxic comments. This app detects a person's incoming replies, and automatically hides a reply based on the “score” that indicates how confident Perspective is that a comment is similar to toxic comments it’s seen in the past. This is an open source template app developed by X. We encourage you to personalize it to build tools for your users. + +[Use app ▸](https://quintessential-yoke.glitch.me "Use app ▸") + +[Jigsaw on X](https://x.com/jigsaw "Jigsaw on X") + + ![Reshuffle](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 150 150%22%3E%3C/svg%3E) + +**Reshuffle** + +Reshuffle is a platform to connect business applications with flexible scripts. They built an integration script to detect and hide replies that include keywords you define. To try it out, make sure you have a valid app enabled for Hide replies, then follow the instructions in the repo. + +[Go to app ▸](https://github.com/reshufflehq/reshuffle "Go to app ▸") + +[Reshuffle on X](https://x.com/reshufflehq "Reshuffle on X") + + ![Hide unwanted replies](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 396 397%22%3E%3C/svg%3E) + +**Hide unwanted replies** + +Dara Oladosu, the developer behind the popular app QuotedReplies, built an app that automatically hides replies that meet some of the criteria that he’s determined are more likely to exhibit abusive behavior, including replies that contain certain keywords he’s muted in the past. + +[Go to app ▸](https://hideunwantedreplies.com/ "Go to app ▸") + +[Dara Oladosu on X](https://x.com/dara_tobi "Dara Oladosu on X") + + ![Pandaflow](data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 94 94%22%3E%3C/svg%3E) + +**Pandaflow** + +Pandaflow is a no code platform to automate workflows. They integrate the endpoint so users can programmatically hide replies based on a custom flow they define. + +[Go to app ▸](https://pandaflow.io/ "Go to app ▸") + +[Pandaflow on X](https://x.com/pandaflowio "Pandaflow on X") + diff --git a/x-api/posts/hide-replies/integrate/manage-replies-by-topic.mdx b/x-api/posts/hide-replies/integrate/manage-replies-by-topic.mdx index 051f86ca8..d4e9ab224 100644 --- a/x-api/posts/hide-replies/integrate/manage-replies-by-topic.mdx +++ b/x-api/posts/hide-replies/integrate/manage-replies-by-topic.mdx @@ -1,33 +1,34 @@ ---- -title: Manage replies by topic -sidebarTitle: Manage replies by topic -keywords: ["manage replies by topic", "topic-based moderation", "reply moderation by topic", "hide replies by topic", "topic filtering"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Manage replies by topic - -Through the hide replies endpoint, you can build integrations to help people and brands keep their conversation on topic. This page shows how to manage a conversation using the hide replies and [recent search](/x-api/posts/recent-search) endpoints. - -Recent search has functionality to a conversation and its replies, and the Post payload returns [Post annotations](/x-api/fundamentals/post-annotations) to help you understand the context and topic of each Post, regardless of language. - -The app's flow will have controls to display and manage a conversation: - -1. It asks the user’s permission to read their Posts and manage their replies. -2. It pulls a recent conversation from a Post URL, and checks that the conversation is from the authenticating user. -3. It will call the recent search endpoint to display each Post in the conversation. The request will include a conversation ID search query and the annotation expansion to determine if the Post is sports-related or not, according to X's interpretation of the Post. -4. It calls Hide replies to hide a reply when the user chooses to do so. It will also provide a way to undo this action in case, so that the user is always in control.  - -5. For longer conversations, it will provide controls to [paginate through search results](/x-api/posts/search/integrate/paginate). -   - -#### Optimize for the user (and for usage) - -You can design a flow in a way that puts the user in control of any action they intend to make. Keeping this principle in mind also helps you build an integration that can optimize for Post consumption. - -1. Because the authenticated user can only manage conversations they started, your flow should terminate early when that's not the case. - * Make an initial Post lookup request. Terminate the flow early if the Post URL is not valid or the conversation was not started by the authenticating user. - * This way, your app doesn't have to make a recent search request if the conversation cannot be moderated by the authenticated user. -2. Request [user and Post fields](/x-api/fundamentals/fields) in the same request to avoid making separate requests. This approach can also improve your app's performance. -3. Avoid making requests when needed. This app caches a reply's hidden status in the user's browser. This is useful for larger conversations, where the user may want to pick up their moderation efforts at a later stage, and it helps your app optimize requests to hide or unhide replies. +--- +title: Manage replies by topic +sidebarTitle: Manage replies by topic +keywords: ["manage replies by topic", "topic-based moderation", "reply moderation by topic", "hide replies by topic", "topic filtering"] + +description: Through the hide replies endpoint, you can build integrations to help people and brands keep their conversation on topic. This page shows how to manage ...--- + +import { Button } from '/snippets/button.mdx'; + +### Manage replies by topic + +Through the hide replies endpoint, you can build integrations to help people and brands keep their conversation on topic. This page shows how to manage a conversation using the hide replies and [recent search](/x-api/posts/recent-search) endpoints. + +Recent search has functionality to a conversation and its replies, and the Post payload returns [Post annotations](/x-api/fundamentals/post-annotations) to help you understand the context and topic of each Post, regardless of language. + +The app's flow will have controls to display and manage a conversation: + +1. It asks the user’s permission to read their Posts and manage their replies. +2. It pulls a recent conversation from a Post URL, and checks that the conversation is from the authenticating user. +3. It will call the recent search endpoint to display each Post in the conversation. The request will include a conversation ID search query and the annotation expansion to determine if the Post is sports-related or not, according to X's interpretation of the Post. +4. It calls Hide replies to hide a reply when the user chooses to do so. It will also provide a way to undo this action in case, so that the user is always in control.  + +5. For longer conversations, it will provide controls to [paginate through search results](/x-api/posts/search/integrate/paginate). +   + +#### Optimize for the user (and for usage) + +You can design a flow in a way that puts the user in control of any action they intend to make. Keeping this principle in mind also helps you build an integration that can optimize for Post consumption. + +1. Because the authenticated user can only manage conversations they started, your flow should terminate early when that's not the case. + * Make an initial Post lookup request. Terminate the flow early if the Post URL is not valid or the conversation was not started by the authenticating user. + * This way, your app doesn't have to make a recent search request if the conversation cannot be moderated by the authenticated user. +2. Request [user and Post fields](/x-api/fundamentals/fields) in the same request to avoid making separate requests. This approach can also improve your app's performance. +3. Avoid making requests when needed. This app caches a reply's hidden status in the user's browser. This is useful for larger conversations, where the user may want to pick up their moderation efforts at a later stage, and it helps your app optimize requests to hide or unhide replies. diff --git a/x-api/posts/hide-replies/integrate/manage-replies-in-realtime.mdx b/x-api/posts/hide-replies/integrate/manage-replies-in-realtime.mdx index b76bdbf05..119fb41cd 100644 --- a/x-api/posts/hide-replies/integrate/manage-replies-in-realtime.mdx +++ b/x-api/posts/hide-replies/integrate/manage-replies-in-realtime.mdx @@ -1,27 +1,28 @@ ---- -title: Manage replies by topic -sidebarTitle: Manage replies by topic -keywords: ["manage replies", "hide replies integration", "reply moderation", "real-time moderation", "reply management", "moderate replies"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Manage replies in realtime - -With the hide replies endpoint, you can build a workflow to helps your users hide replies that have a very high-probability of being irrelevant. - -Useful apps often combine technologies so that they can be valuable to their users. This page shows how to hide replies by using the [Perspective API](https://www.perspectiveapi.com/). This API is an artificial intelligence trained by [Jigsaw](https://jigsaw.google.com/), a unit within Google, to detect toxic comments. The application logic will work in the following way: - -1. It asks the user’s permission to read their Posts and hide or unhide their replies. -2. It uses the [Account Activity API](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/subscribe-account-activity/overview) to detect incoming replies. -3. It asks the Perspective API to give a “score” (a number between 0 and 1) that indicates how confident their algorithm is that a comment is similar to toxic comments it’s seen in the past. (Perspective does not store the text sent to the service). -4. It calls hide replies if the algorithm’s score is very high. - -#### Strive for transparency - -Because Perspective is not trained on actual Posts, certain language nuances may cause this app to hide a reply that a user wants to remain unhidden. Regardless of the technology or the approach you use when designing your app, always make the best possible effort to ensure that your users understand what your app has hidden and can make changes. - -* The best option is to always trust the user and to give them full control over their decisions. This means your user experience should include controls to undo any action taken by your app on behalf of the user. -* When using an artificial intelligence, your app should use a very high confidence threshold to detect and hide Posts. -* Not everybody uses the same words, and your app should be designed to avoid any bias. Be mindful of reclaimed words and slang that may lead to false positives. -* If you are training an artificial intelligence, consider adopting a model that closely reflects language often used on X. +--- +title: Manage replies by topic +sidebarTitle: Manage replies by topic +keywords: ["manage replies", "hide replies integration", "reply moderation", "real-time moderation", "reply management", "moderate replies"] + +description: With the hide replies endpoint, you can build a workflow to helps your users hide replies that have a very high-probability of being irrelevant. Useful ...--- + +import { Button } from '/snippets/button.mdx'; + +### Manage replies in realtime + +With the hide replies endpoint, you can build a workflow to helps your users hide replies that have a very high-probability of being irrelevant. + +Useful apps often combine technologies so that they can be valuable to their users. This page shows how to hide replies by using the [Perspective API](https://www.perspectiveapi.com/). This API is an artificial intelligence trained by [Jigsaw](https://jigsaw.google.com/), a unit within Google, to detect toxic comments. The application logic will work in the following way: + +1. It asks the user’s permission to read their Posts and hide or unhide their replies. +2. It uses the [Account Activity API](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/subscribe-account-activity/overview) to detect incoming replies. +3. It asks the Perspective API to give a “score” (a number between 0 and 1) that indicates how confident their algorithm is that a comment is similar to toxic comments it’s seen in the past. (Perspective does not store the text sent to the service). +4. It calls hide replies if the algorithm’s score is very high. + +#### Strive for transparency + +Because Perspective is not trained on actual Posts, certain language nuances may cause this app to hide a reply that a user wants to remain unhidden. Regardless of the technology or the approach you use when designing your app, always make the best possible effort to ensure that your users understand what your app has hidden and can make changes. + +* The best option is to always trust the user and to give them full control over their decisions. This means your user experience should include controls to undo any action taken by your app on behalf of the user. +* When using an artificial intelligence, your app should use a very high confidence threshold to detect and hide Posts. +* Not everybody uses the same words, and your app should be designed to avoid any bias. Be mindful of reclaimed words and slang that may lead to false positives. +* If you are training an artificial intelligence, consider adopting a model that closely reflects language often used on X. diff --git a/x-api/posts/hide-replies/migrate.mdx b/x-api/posts/hide-replies/migrate.mdx index 4f2e8d34c..62433a19a 100644 --- a/x-api/posts/hide-replies/migrate.mdx +++ b/x-api/posts/hide-replies/migrate.mdx @@ -1,99 +1,101 @@ ---- -title: Migration guide -sidebarTitle: Migration guide -keywords: ["hide replies migration", "hide replies migrate", "migration guide", "migrate hide replies", "v2 migration"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing X API's hide replies endpoints - -The v2 hide replies endpoint is replacing the Labs hide replies endpoint. If you have code, apps, or tools that use the Labs version of this endpoint, and are considering migrating to the newer X API v2 endpoint, then this guide is for you. - -In order to use the new X API v2 (including the hide replies endpoint), you will need to [opt in to the new Developer Console](https://developer.x.com/en/portal/opt-in), create a [Project](/resources/fundamentals/developer-apps), and add an App to that Project. You can then use the credentials associated with that App to make requests to the hide replies endpoint. Adding the same App that's enrolled for the Labs v2 hide replies endpoint will keep your users authenticated. - -The following table compares the differences between Labs and the newer X API v2 endpoint: - - -| **Description** | **Labs v2** | **X API v2** | -| :--- | :--- | :--- | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /labs/2/tweets/:id/hidden | /2/tweets/:id/hidden | -| Authentication | OAuth 1.0a User context | OAuth 1.0a User context | -| HTTP methods supported | PUT | PUT | -| Default request rate limits | 10 requests per 15 minutes (shared across all authenticated users) | 50 requests per 15 min (for each authenticated user) | -| Can hide replies | ✔︎ | ✔︎ | -| Can unhide a previously hidden reply | ✔︎ | ✔︎ | -| Can hide or unhide replies multiple times | ✔︎ | ✔︎ | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [project](/resources/fundamentals/developer-apps) | | ✔ | - ---- - -## Code examples - -### Hide a reply (v2) - - - -```bash cURL -curl -X PUT "https://api.x.com/2/tweets/1234567890/hidden" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"hidden": true}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/tweets/1234567890/hidden" -response = requests.put(url, auth=auth, json={"hidden": True}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Hide a reply -response = client.posts.hide_reply("1234567890", hidden=True) -print(f"Hidden: {response.data.hidden}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Hide a reply -const response = await client.posts.hideReply("1234567890", { hidden: true }); -console.log(`Hidden: ${response.data?.hidden}`); -``` - - - -**Other migration resources** - -[X API migration hub](/x-api/migrate/overview) +--- +title: Migration guide +sidebarTitle: Migration guide +keywords: ["hide replies migration", "hide replies migrate", "migration guide", "migrate hide replies", "v2 migration"] + + +--- + +import { Button } from '/snippets/button.mdx'; + +## Comparing X API's hide replies endpoints + +The v2 hide replies endpoint is replacing the Labs hide replies endpoint. If you have code, apps, or tools that use the Labs version of this endpoint, and are considering migrating to the newer X API v2 endpoint, then this guide is for you. + +In order to use the new X API v2 (including the hide replies endpoint), you will need to [opt in to the new Developer Console](https://developer.x.com/en/portal/opt-in), create a [Project](/resources/fundamentals/developer-apps), and add an App to that Project. You can then use the credentials associated with that App to make requests to the hide replies endpoint. Adding the same App that's enrolled for the Labs v2 hide replies endpoint will keep your users authenticated. + +The following table compares the differences between Labs and the newer X API v2 endpoint: + + +| **Description** | **Labs v2** | **X API v2** | +| :--- | :--- | :--- | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /labs/2/tweets/:id/hidden | /2/tweets/:id/hidden | +| Authentication | OAuth 1.0a User context | OAuth 1.0a User context | +| HTTP methods supported | PUT | PUT | +| Default request rate limits | 10 requests per 15 minutes (shared across all authenticated users) | 50 requests per 15 min (for each authenticated user) | +| Can hide replies | ✔︎ | ✔︎ | +| Can unhide a previously hidden reply | ✔︎ | ✔︎ | +| Can hide or unhide replies multiple times | ✔︎ | ✔︎ | +| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [project](/resources/fundamentals/developer-apps) | | ✔ | + +--- + +## Code examples + +### Hide a reply (v2) + + + +```bash cURL +curl -X PUT "https://api.x.com/2/tweets/1234567890/hidden" \ + -H "Authorization: OAuth ..." \ + -H "Content-Type: application/json" \ + -d '{"hidden": true}' +``` + +```python Python +# Requires OAuth 1.0a User Context authentication +import requests +from requests_oauthlib import OAuth1 + +auth = OAuth1( + "API_KEY", "API_SECRET", + "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" +) + +url = "https://api.x.com/2/tweets/1234567890/hidden" +response = requests.put(url, auth=auth, json={"hidden": True}) +print(response.json()) +``` + +```python Python SDK +from xdk import Client +from xdk.oauth1_auth import OAuth1 + +oauth1 = OAuth1( + api_key="YOUR_API_KEY", + api_secret="YOUR_API_SECRET", + access_token="YOUR_ACCESS_TOKEN", + access_token_secret="YOUR_ACCESS_TOKEN_SECRET" +) + +client = Client(auth=oauth1) + +# Hide a reply +response = client.posts.hide_reply("1234567890", hidden=True) +print(f"Hidden: {response.data.hidden}") +``` + +```javascript JavaScript SDK +import { Client, OAuth1 } from "@xdevplatform/xdk"; + +const oauth1 = new OAuth1({ + apiKey: "YOUR_API_KEY", + apiSecret: "YOUR_API_SECRET", + accessToken: "YOUR_ACCESS_TOKEN", + accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", +}); + +const client = new Client({ oauth1 }); + +// Hide a reply +const response = await client.posts.hideReply("1234567890", { hidden: true }); +console.log(`Hidden: ${response.data?.hidden}`); +``` + + + +**Other migration resources** + +[X API migration hub](/x-api/migrate/overview) diff --git a/x-api/posts/hide-reply.mdx b/x-api/posts/hide-reply.mdx index bcb0c86cb..f5901e5a7 100644 --- a/x-api/posts/hide-reply.mdx +++ b/x-api/posts/hide-reply.mdx @@ -1,3 +1,4 @@ --- openapi: put /2/tweets/{tweet_id}/hidden ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.mdx b/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.mdx index 98e3ad0d3..755dafb55 100644 --- a/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.mdx +++ b/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.mdx @@ -1,204 +1,37 @@ ---- -title: Likes lookup -sidebarTitle: Likes lookup -keywords: ["likes lookup migration", "v1.1 to v2 likes lookup", "migrate likes lookup", "standard to v2 likes", "likes migration"] ---- - -### Likes lookup: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [GET favorites/list](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/get-favorites-list) endpoint, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 Likes lookup endpoints. - -With v2, we’ve also introduced a new liked users endpoint which allows you to get information about a Post's liking users. - -* **Similarities** - * Authentiation - * Rate limits -* **Differences** - * Endpoint URLs - - * Request limitations - * App and Project requirements - - * Request parameters - * New JSON format - -#### Similarities - -**Authentication** - -Both the standard v1.1 and X API v2 Likes lookup endpoints use [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2) or [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). Therefore, if you were previously using the [GET favorites/list endpoints](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/get-favorites-list) standard v1.1 endpoints, you can continue using the same authentication method if you migrate to the X API v2 version if you wish.  - -Depending on your authentication library/package of choice, Bearer Token authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate a Bearer Token, see [this OAuth 2.0 Bearer Token guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only).  -  - -**Rate limits** - -The standard v1.1 GET favorites/list endpoint has a 75 requests per 15 minutes per user rate limit. The corresponding liked Posts endpoint in v2 also has this same rate limit. However, this v2 endpoint also has an additional rate limit of 75 requests per 15 minutes per App. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * GET https://api.x.com/1.1/favorites/list.json - (list of Posts which are by the specified user) - * There is no v1.1 equivalent to the v2 liking users endpoint -* X API v2 endpoint: - * GET https://api.x.com/2/users/:id/liked_tweets - (list of Posts which are liked by the specified user ID) - * GET https://api.x.com/2/tweets/:id/liking_users - (list of users who liked the specified Post ID) - -**Request limitations** - -The v2 liked Posts endpoint allows you to request 5 to 100 Posts per request, but you can request all likes of a Post using pagination tokens. The v1.1 GET favorites/list endpoint also allows you to pull all likes of Posts, but you can pull from 20 to 200 Posts per request. - -For the v2 liking users endpoint, you are limited to 100 liking users per Post.  -  - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Request parameters** - -The following standard v1.1 request parameters accepted two request query parameters (user_id or screen_name). The X API v2 only accepts the numerical user ID, and it must be passed as part of the endpoint path. - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. For the standard endpoints, there are several parameters that you could use to identify which fields or sets of fields would return in the payload, while the X API v2 version simplifies these different parameters into [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions).  -  - -**New JSON format** - -X API v2 is introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return user objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values. -   - -In addition to the changes that we made to our new JSON format, we also introduced a new set of fields to the Post object including the following: - -* [conversation_id](/x-api/fundamentals/conversation-id) -* Two new [Post annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields - ---- - -## Code examples - -### Get liked Posts (v2) - - - -```bash cURL -curl "https://api.x.com/2/users/2244994945/liked_tweets?tweet.fields=created_at,public_metrics&max_results=100" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/users/2244994945/liked_tweets" - -params = { - "tweet.fields": "created_at,public_metrics", - "max_results": 100 -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user's liked Posts -for page in client.posts.get_liked_posts( - "2244994945", - tweet_fields=["created_at", "public_metrics"], - max_results=100 -): - for post in page.data: - print(f"{post.text[:50]}... - Likes: {post.public_metrics.like_count}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get user's liked Posts -const paginator = client.posts.getLikedPosts("2244994945", { - tweetFields: ["created_at", "public_metrics"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`${post.text?.slice(0, 50)}... - Likes: ${post.public_metrics?.like_count}`); - }); -} -``` - - - -### Get liking users (v2) - - - -```bash cURL -curl "https://api.x.com/2/tweets/1234567890/liking_users?user.fields=username,verified" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/1234567890/liking_users" - -params = {"user.fields": "username,verified"} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get users who liked a Post -response = client.posts.get_liking_users( - "1234567890", - user_fields=["username", "verified"] -) -for user in response.data: - print(f"{user.username} - Verified: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get users who liked a Post -const response = await client.posts.getLikingUsers("1234567890", { - userFields: ["username", "verified"], -}); - -response.data?.forEach((user) => { - console.log(`${user.username} - Verified: ${user.verified}`); -}); -``` - - +--- +title: Likes lookup +sidebarTitle: Likes lookup +keywords: ["likes lookup migration", "v1.1 to v2 likes lookup", "migrate likes lookup", "standard to v2 likes", "likes migration"] + + +--- +### Likes lookup: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [GET favorites/list](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/get-favorites-list) endpoint, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 Likes lookup endpoints. + +With v2, we’ve also introduced a new liked users endpoint which allows you to get information about a Post's liking users. + +* **Similarities** + * Authentiation + * Rate limits +* **Differences** + * Endpoint URLs + + * Request limitations + * App and Project requirements + + * Request parameters + * New JSON format + +#### Similarities + +**Authentication** + +Both the standard v1.1 and X API v2 Likes lookup endpoints use [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2) or [OAuth 2.0 Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). Therefore, if you were previously using the [GET favorites/list endpoints](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/api-reference/get-favorites-list) standard v1.1 endpoints, you can continue using the same authentication method if you migrate to the X API v2 version if you wish.  + +Depending on your authentication library/package of choice, Bearer Token authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate a Bearer Token, see [this OAuth 2.0 Bearer Token guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only).  +  + +**Rate limits** + +The standard v1.1 GET favorites/list endpoint has a 75 requests per 15 minutes per user rate limit. The corresponding liked Posts endpoint in v2 also has this sam \ No newline at end of file diff --git a/x-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.mdx b/x-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.mdx index 10fccc0dc..feb8f9756 100644 --- a/x-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.mdx +++ b/x-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.mdx @@ -1,183 +1,42 @@ ---- -title: Manage Likes -sidebarTitle: Manage Likes -keywords: ["manage likes migration", "v1.1 to v2 manage likes", "migrate manage likes", "standard to v2 likes", "likes migration"] ---- - -### Manage Likes: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST favorites/create](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-create) and [POST favorites/destroy](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage Likes endpoints. - -* **Similarities** - * OAuth 1.0a User Context -* **Differences** - * Endpoint URLs and HTTP methods - * App and Project requirements - * Request parameters - -#### Similarities - -**OAuth 1.0a User Context authentication method** - -Both the endpoint versions support [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 manage favorites endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs and HTTP methods** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/favorites/create.json - (like a Post) - * POST https://api.x.com/1.1/favorites/destroy.json - (unlike a Post) -* X API v2 endpoint: - * POST https://api.x.com/2/tweets/:id/likes - (like a Post) - * DELETE https://api.x.com/2/tweets/:id/likes/:tweet_id - (unlike a Post)  - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. - - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard v1.1 | X API v2 | -| :--- | :--- | -| id | id | -| includes_entities | No equivalent | - -Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters for the POST endpoint or path parameters for the DELETE endpoint. - -Also, an id of the user liking a Post is not required when using the standard v1.1 endpoints since the [Access Tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) passed with [OAuth 1.0a User Context](/resources/fundamentals/authentication) infer which user is initiating the like/unlike. - ---- - -## Code examples - -### Like a Post (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123456789/likes" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"tweet_id": "1234567890"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/likes" -response = requests.post(url, auth=auth, json={"tweet_id": "1234567890"}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Like a Post -response = client.posts.like(user_id="123456789", tweet_id="1234567890") -print(f"Liked: {response.data.liked}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Like a Post -const response = await client.posts.like("123456789", { tweetId: "1234567890" }); -console.log(`Liked: ${response.data?.liked}`); -``` - - - -### Unlike a Post (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/users/123456789/likes/1234567890" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/likes/1234567890" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Unlike a Post -response = client.posts.unlike(user_id="123456789", tweet_id="1234567890") -print(f"Liked: {response.data.liked}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Unlike a Post -const response = await client.posts.unlike("123456789", "1234567890"); -console.log(`Liked: ${response.data?.liked}`); -``` - - +--- +title: Manage Likes +sidebarTitle: Manage Likes +keywords: ["manage likes migration", "v1.1 to v2 manage likes", "migrate manage likes", "standard to v2 likes", "likes migration"] + + +--- +### Manage Likes: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST favorites/create](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-create) and [POST favorites/destroy](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage Likes endpoints. + +* **Similarities** + * OAuth 1.0a User Context +* **Differences** + * Endpoint URLs and HTTP methods + * App and Project requirements + * Request parameters + +#### Similarities + +**OAuth 1.0a User Context authentication method** + +Both the endpoint versions support [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 manage favorites endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs and HTTP methods** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/favorites/create.json + (like a Post) + * POST https://api.x.com/1.1/favorites/destroy.json + (unlike a Post) +* X API v2 endpoint: + * POST https://api.x.com/2/tweets/:id/likes + (like a Post) + * DELETE https://api.x.com/2/tweets/:id/likes/:tweet_id + (unlike a Post)  + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated \ No newline at end of file diff --git a/x-api/posts/likes/migrate/overview.mdx b/x-api/posts/likes/migrate/overview.mdx index d53d0da26..55b0fa147 100644 --- a/x-api/posts/likes/migrate/overview.mdx +++ b/x-api/posts/likes/migrate/overview.mdx @@ -1,75 +1,75 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["likes migration", "likes migrate", "v1.1 to v2 likes", "likes migration guide", "migrate likes"] ---- - -## Comparing X API’s Likes endpoints - - -These guides will focus on the following areas: - -* **API request parameters** - The X API v2 endpoint introduces a new set of request parameters. While some parameters will be familiar, especially for those integrating with Labs, there are many important differences such as the introduction of the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. - -* **App and Project requirements** \- To access the X API v2, you will need to use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) - -#### Likes lookup -**Users who have liked a Post** - -The liked users endpoint is new functionality for v2, allowing you to get information about a Post's liking users. - -| Description | X API v2 | -| :--- | :--- | -| HTTP methods supported | GET | -| Host domain | https://api.x.com | -| Endpoint path | /2/tweets/:id/liking_users | -| [Authentication](/resources/fundamentals/authentication) | OAuth 2.0 Bearer Token

OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min (per App)

75 requests per 15 min (per user) | - -**Posts liked by a user** - -The following tables compare the standard v1.1 [GET favorites/list](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-favorites-list) endpoint and the X API v2 liked Posts endpoints: - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | GET | GET | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/favorites/list.json | /2/users/:id/liked_tweets | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 2.0 Bearer Token

OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min | 75 requests per 15 min (per App)

75 requests per 15 min (per user) | -| Data formats | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | - - -#### Manage Likes - -The v2 manage Likes endpoints replace the v1.1 [POST favorites/create](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-create) and [POST favorites/destroy](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-destroy) endpoints. - -The following tables compare the standard v1.1 and X API v2 manage Like endpoints: - -#### Like a Post - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | POST | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/favorites/create.json | /2/users/:id/likes | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 1000 requests per 24 hours (per user)

1000 requests per 24 hours (per App) | 50 requests per 15 min (per user)

1000 requests per 24 hours (per user, shared with DELETE) | - -#### Unlike a Post - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | DELETE | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/favorites/destroy.json | /2/users/:id/likes/:tweet_id | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 1000 requests per 24 hours (per user)

1000 requests per 24 hours (per App) | 50 requests per 15 min (per user)

1000 requests per 24 hours (per user, shared with POST) | - -**Other migration resources** - -[Likes lookup: Standard v1.1 to X API v2](/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2) - -[Manage Likes: Standard v1.1 to X API v2](/x-api/posts/likes#manage-likes-standard-v1-1-compared-to-x-api-v2) - +--- +title: Overview +sidebarTitle: Overview +keywords: ["likes migration", "likes migrate", "v1.1 to v2 likes", "likes migration guide", "migrate likes"] + + +## Comparing X API’s Likes endpoints + + +These guides will focus on the following areas: + +* **API request parameters** - The X API v2 endpoint introduces a new set of request parameters. While some parameters will be familiar, especially for those integrating with Labs, there are many important differences such as the introduction of the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. + +* **App and Project requirements** \- To access the X API v2, you will need to use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) + +#### Likes lookup +**Users who have liked a Post** + +The liked users endpoint is new functionality for v2, allowing you to get information about a Post's liking users. + +| Description | X API v2 | +| :--- | :--- | +| HTTP methods supported | GET | +| Host domain | https://api.x.com | +| Endpoint path | /2/tweets/:id/liking_users | +| [Authentication](/resources/fundamentals/authentication) | OAuth 2.0 Bearer Token

OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min (per App)

75 requests per 15 min (per user) | + +**Posts liked by a user** + +The following tables compare the standard v1.1 [GET favorites/list](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-favorites-list) endpoint and the X API v2 liked Posts endpoints: + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | GET | GET | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/favorites/list.json | /2/users/:id/liked_tweets | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 2.0 Bearer Token

OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min | 75 requests per 15 min (per App)

75 requests per 15 min (per user) | +| Data formats | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | + + +#### Manage Likes + +The v2 manage Likes endpoints replace the v1.1 [POST favorites/create](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-create) and [POST favorites/destroy](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-destroy) endpoints. + +The following tables compare the standard v1.1 and X API v2 manage Like endpoints: + +#### Like a Post + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | POST | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/favorites/create.json | /2/users/:id/likes | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 1000 requests per 24 hours (per user)

1000 requests per 24 hours (per App) | 50 requests per 15 min (per user)

1000 requests per 24 hours (per user, shared with DELETE) | + +#### Unlike a Post + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | DELETE | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/favorites/destroy.json | /2/users/:id/likes/:tweet_id | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 1000 requests per 24 hours (per user)

1000 requests per 24 hours (per App) | 50 requests per 15 min (per user)

1000 requests per 24 hours (per user, shared with POST) | + +**Other migration resources** + +[Likes lookup: Standard v1.1 to X API v2](/x-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2) + +[Manage Likes: Standard v1.1 to X API v2](/x-api/posts/likes#manage-likes-standard-v1-1-compared-to-x-api-v2) + [X API migration hub](/x-api/migrate/overview) \ No newline at end of file diff --git a/x-api/posts/lookup/integrate.mdx b/x-api/posts/lookup/integrate.mdx index 7fdb77247..eca611eaf 100644 --- a/x-api/posts/lookup/integrate.mdx +++ b/x-api/posts/lookup/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating Post lookup keywords: ["post lookup integration", "lookup integration guide", "lookup implementation", "lookup setup", "tweet lookup integration"] --- diff --git a/x-api/posts/lookup/migrate/overview.mdx b/x-api/posts/lookup/migrate/overview.mdx index e86c95630..a158302f0 100644 --- a/x-api/posts/lookup/migrate/overview.mdx +++ b/x-api/posts/lookup/migrate/overview.mdx @@ -8,8 +8,6 @@ keywords: ["post lookup migration", "lookup migrate", "v1.1 to v2 lookup", "look The v2 Posts lookup endpoints replace the standard v1.1 [GET statuses/lookup](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-lookup) and [GET statuses/show](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-show-id) endpoints. This guide is for developers migrating from these older versions to X API v2. ---- - ## Endpoint Comparison Table | Description | Standard v1.1 | X API v2 | diff --git a/x-api/posts/lookup/migrate/standard-to-twitter-api-v2.mdx b/x-api/posts/lookup/migrate/standard-to-twitter-api-v2.mdx index 09e171b39..9be3fcf0c 100644 --- a/x-api/posts/lookup/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/posts/lookup/migrate/standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "lookup migration", "migrate lookup", "standard to v2", "v1 to v2 lookup", "migration guide"] ---- + +--- ## Standard v1.1 compared to X API v2 If you have been working with the standard v1.1 GET statuses/show and GET statuses/lookup, this guide will help you understand the similarities and differences between the standard and X API v2 Posts lookup endpoints. @@ -31,216 +32,4 @@ App-Only authentication is likely the easiest way to get started. To learn how t #### Posts per Request Limits -The v1.1 [GET statuses/lookup](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-lookup) endpoint allows you to specify up to 100 Posts per request. This also applies to the GET /tweets endpoint. To specify a full 100 Posts, use the `ids` parameter as a query parameter with a comma-separated list of [Post IDs](/resources/fundamentals/x-ids). - -**Support for Post Edit History and Metadata** - -Both versions provide metadata that describes any edit history. Check out the Post lookup API References and the [Edit Posts fundamentals page](/x-api/fundamentals/edit-posts) for more details. - -### Differences - -#### Endpoint URLs - -- **Standard v1.1 endpoints:** - - `https://api.x.com/1.1/statuses/show` - - `https://api.x.com/1.1/statuses/lookup` - -- **X API v2 endpoint:** - - `https://api.x.com/2/tweets` - - `https://api.x.com/2/tweets/:id` - -#### App and Project Requirements - -X API v2 endpoints require credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) for authentication. X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. - -#### Response Data Format - -A significant difference between standard v1.1 and X API v2 endpoint versions is how fields are selected in the payload. - -For standard endpoints, many response fields are included by default, with options to use parameters to specify additional fields. - -X API v2, however, only delivers the Post `id` and `text` fields by default. Additional fields and objects require the use of [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. The expanded fields return in an `includes` object within the response, which can be matched to the primary Post object by matching IDs. - -For more on using fields and expansions, see the [guide on how to use fields and expansions](/x-api/fundamentals/data-dictionary). A [data format migration guide](/x-api/fundamentals/fields) also maps standard v1.1 fields to the newer v2 fields. - -Additionally, X API v2 introduces new JSON designs for objects, including the Post and [user](/x-api/fundamentals/data-dictionary#user) objects: - -- Standard endpoints return Post objects in a `statuses` array, while X API v2 uses a `data` array. -- Retweeted and Quoted Tweets in X API v2 replace "statuses" terminology. -- New terminology such as `like` replaces terms like `favorites` and `favourites`. -- Attributes with no values (e.g., `null`) are not included in X API v2 payloads. - -The Post object in X API v2 includes new fields such as: -- `conversation_id` -- Two new [annotations](/x-api/fundamentals/post-annotations) fields (`context` and `entities`) -- New [metrics](/x-api/fundamentals/metrics) fields -- `reply_setting` field showing who can reply to a given Post - -#### Request Parameters - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard | X API v2 | -|:----------|:----------| -| `id` | `ids` | - -Certain standard v1.1 parameters are **not** supported in X API v2: - -| Standard | Comment | -|:---------------------|:------------------------------------------------------------------------------------------------------------------------------| -| `tweet_mode` | Replaced by fields and expansions functionality. | -| `trim_user` | Replaced by fields and expansions. Use `author_id` expansion and `user.fields` for user data. | -| `include_my_retweet`| Provides the ID of the source Post for Retweeted Posts by the authenticating user. | -| `include_entities` | Use fields and expansions to control entities in the payload. | -| `include_ext_alt_text` | Adds `ext_alt_text` field in media entity if alt text is present. | -| `include_card_uri` | Adds `card_uri` when an ads card is attached. | -| `map` | Returns the Post ID and error message for unavailable Posts in X API v2, as opposed to nullified fields in v1.1. | - -### Code Examples - -The following examples show standard v1.1 endpoints and their v2 equivalents. Replace credentials with your actual tokens. For v2 endpoints, the token must belong to a [developer App](/resources/fundamentals/developer-apps/overview) within a [Project](/resources/fundamentals/developer-apps/overview). - -The response payloads from v1.1 will differ from v2. With v2, you can request different fields with the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. - -**Multiple Posts lookup: v1.1 `GET statuses/lookup` → v2 `GET /tweets`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/statuses/lookup.json?id=1460323737035677698%2C1460323743339741184' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/tweets?ids=1460323737035677698%2C1460323743339741184&tweet.fields=created_at&expansions=author_id&user.fields=created_at' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets" - -params = { - "ids": "1460323737035677698,1460323743339741184", - "tweet.fields": "created_at", - "expansions": "author_id", - "user.fields": "created_at" -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get multiple Posts by IDs with fields and expansions -response = client.posts.get_posts( - ids=["1460323737035677698", "1460323743339741184"], - tweet_fields=["created_at"], - expansions=["author_id"], - user_fields=["created_at"] -) - -for post in response.data: - print(f"Post: {post.text}") - print(f"Created at: {post.created_at}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get multiple Posts by IDs with fields and expansions -const response = await client.posts.getPosts({ - ids: ["1460323737035677698", "1460323743339741184"], - tweetFields: ["created_at"], - expansions: ["author_id"], - userFields: ["created_at"], -}); - -response.data?.forEach((post) => { - console.log(`Post: ${post.text}`); - console.log(`Created at: ${post.created_at}`); -}); -``` - - - -**Single Post lookup: v1.1 `GET statuses/show/:id` → v2 `GET /tweets/:id`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/statuses/show.json?id=1460323737035677698' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/tweets/1460323737035677698?tweet.fields=created_at&expansions=author_id&user.fields=created_at' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/1460323737035677698" - -params = { - "tweet.fields": "created_at", - "expansions": "author_id", - "user.fields": "created_at" -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get a single Post by ID -response = client.posts.get( - "1460323737035677698", - tweet_fields=["created_at"], - expansions=["author_id"], - user_fields=["created_at"] -) - -print(f"Post: {response.data.text}") -print(f"Created at: {response.data.created_at}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get a single Post by ID -const response = await client.posts.get("1460323737035677698", { - tweetFields: ["created_at"], - expansions: ["author_id"], - userFields: ["created_at"], -}); - -console.log(`Post: ${response.data?.text}`); -console.log(`Created at: ${response.data?.created_at}`); -``` - - \ No newline at end of file +The v1.1 [GET statuses/lookup](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-lookup) endpoint allows you to specify up to 100 Posts per request. This also applies to the GET /tweets endpoint. To specify a full 100 Posts, use the `ids` parameter as a query parameter wi \ No newline at end of file diff --git a/x-api/posts/manage-tweets/integrate.mdx b/x-api/posts/manage-tweets/integrate.mdx index e0e62b317..b8680f13c 100644 --- a/x-api/posts/manage-tweets/integrate.mdx +++ b/x-api/posts/manage-tweets/integrate.mdx @@ -2,14 +2,14 @@ title: Integration guide sidebarTitle: Integration guide keywords: ["manage tweets integration", "tweet creation integration", "post tweet integration", "tweet management guide", "create tweet setup"] + + --- import { Button } from '/snippets/button.mdx'; This page covers tools and key concepts for integrating the manage Posts endpoints into your system. ---- - ## Helpful tools Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: diff --git a/x-api/posts/manage-tweets/migrate/overview.mdx b/x-api/posts/manage-tweets/migrate/overview.mdx index cf5131431..0369c21eb 100644 --- a/x-api/posts/manage-tweets/migrate/overview.mdx +++ b/x-api/posts/manage-tweets/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["manage tweets migration", "tweet creation migration", "v1.1 to v2", "migration guide", "migrate tweet creation"] ---- + ## Comparing X API’s manage Posts endpoints diff --git a/x-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.mdx b/x-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.mdx index 08359ce95..a4ee49df1 100644 --- a/x-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "tweet creation migration", "migrate tweet creation", "standard to v2", "v1 to v2 tweets", "migration guide"] ---- + +--- ## Standard v1.1 compared to X API v2 If you have been working with the standard v1.1 [POST statuses/update](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-update) and [POST statuses/destroy/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-destroy-id) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 manage Posts endpoints. @@ -40,108 +41,4 @@ Both the standard v1.1 and X API v2 manage Posts ([POST statuses/update](https:/ ### App and Project requirements -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - -### Request parameters - -The following standard v1.1 request parameters accepted two request query parameters (user_id or screen_name). The X API v2 only accepts the numerical Post ID for the DELETE endpoint, and it must be passed as part of the endpoint path. - -For the POST endpoint, additional parameters will need to be passed in via the JSON body of the request. You can learn more about what parameters are available in the [API reference guide](/x-api/posts/manage-tweets/introduction). - ---- - -## Code examples - -### Create a Post (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/tweets" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"text": "Hello world!"}' -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Create a Post -response = client.posts.create(text="Hello world!") -print(f"Created Post: {response.data.id}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Create a Post -const response = await client.posts.create({ text: "Hello world!" }); -console.log(`Created Post: ${response.data?.id}`); -``` - - - -### Delete a Post (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/tweets/1234567890" \ - -H "Authorization: OAuth ..." -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Delete a Post -response = client.posts.delete("1234567890") -print(f"Deleted: {response.data.deleted}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Delete a Post -const response = await client.posts.delete("1234567890"); -console.log(`Deleted: ${response.data?.deleted}`); -``` - - +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fund \ No newline at end of file diff --git a/x-api/posts/retweets/integrate.mdx b/x-api/posts/retweets/integrate.mdx index 98f715048..cd00ea407 100644 --- a/x-api/posts/retweets/integrate.mdx +++ b/x-api/posts/retweets/integrate.mdx @@ -1,171 +1,169 @@ ---- -title: Integration guide -sidebarTitle: Integration guide -keywords: ["retweets integration", "retweets guide", "retweets integration guide", "retweets implementation", "retweets setup"] ---- - -This page covers tools and key concepts for integrating the Retweet endpoints. - ---- - -## Helpful tools - -Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: - -#### Postman - -Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. - -#### Code samples - -Interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). - -#### Third-party libraries - -Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. - - -### Key concepts - -#### Authentication - -All X API v2 endpoints require for you to authenticate your requests with a set of credentials, also known as keys and tokens. - -You can use either OAuth 1.0a User Context or OAuth 2.0 Bearer Token to authenticate your requests to the Retweets lookup endpoint. - -The manage Retweets endpoints require the use of OAuth 1.0a User Context, which means that you must use a set of API keys and user access tokens to make a successful request. The access tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of access tokens for another user, they must authorize or authenticate your App using the 3-legged OAuth flow. - -Please note that OAuth 1.0a can be tricky to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries) to properly authenticate your requests. - -**Please note** - -If you are requesting the following fields, OAuth 1.0a User Context is required: - -* tweet.fields.non\_public\_metrics -* tweet.fields.promoted_metrics -* tweet.fields.organic_metrics -* media.fields.non\_public\_metrics -* media.fields.promoted_metrics -* media.fields.organic_metrics - -#### Developer Console, Projects, and developer Apps - -To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. - - -#### Rate limits - -Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. - -The manage Retweets endpoints are limited to 50 requests per 15 min (per user). Additionally, for the POST endpoint, you are limited to 300 requests per 3-hour window (per user, per app). - -With the Retweets lookup endpoint, you are limited to 75 requests per 15-min window. Additionally, only the 100 most recent Retweeting users will be returned by this endpoint. - -#### Fields and expansions - -The X API v2 allows users to select exactly which data they want to return from the API using a set of tools called fields and expansions. The expansion parameter allows you to expand objects referenced in the payload. For example, this endpoint allows you to pull the following [expansions](/x-api/fundamentals/expansions): - -* attachments.poll_ids -* attachments.media_keys -* author_id, entities.mentions.username -* geo.place_id -* in\_reply\_to\_user\_id, -* referenced_tweets.id, -* referenced\_tweets.id.author\_id - - -The fields parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. These endpoints delivers Post objects primarily. By default, the Post object returns the id and text fields. To receive additional fields such as tweet.created_at or tweet.entities, you will have to specifically request those using a fields parameter. Some important fields that you may want to consider using in your integration are our poll data, metrics, Post annotations, and conversation ID fields. - -We've added a guide on how to [use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). - ---- - -### Code examples - -#### Get users who retweeted a Post - - - -```bash cURL -curl "https://api.x.com/2/tweets/1234567890/retweeted_by?user.fields=username,verified" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get users who retweeted a Post -response = client.posts.get_retweeted_by( - "1234567890", - user_fields=["username", "verified"] -) -for user in response.data: - print(f"{user.username} - Verified: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get users who retweeted a Post -const response = await client.posts.getRetweetedBy("1234567890", { - userFields: ["username", "verified"], -}); - -response.data?.forEach((user) => { - console.log(`${user.username} - Verified: ${user.verified}`); -}); -``` - - - -#### Retweet a Post - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123/retweets" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"tweet_id": "1234567890"}' -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Retweet a Post -response = client.posts.retweet(user_id="123", tweet_id="1234567890") -print(response.data) -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Retweet a Post -const response = await client.posts.retweet("123", { tweetId: "1234567890" }); -console.log(response.data); -``` - - +--- +title: Integration guide +sidebarTitle: Integration guide +keywords: ["retweets integration", "retweets guide", "retweets integration guide", "retweets implementation", "retweets setup"] +--- + +This page covers tools and key concepts for integrating the Retweet endpoints. + +## Helpful tools + +Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with: + +#### Postman + +Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our ["Using Postman"](/tutorials/postman-getting-started) page. + +#### Code samples + +Interested in getting set up with this endpoint with some code in your preferred coding language? We've got a handful of different code samples available that you can use as a starting point on our [Github page](https://github.com/xdevplatform/Twitter-API-v2-sample-code). + +#### Third-party libraries + +Take advantage of one of our communities' [third-party libraries](/tools-and-libraries) to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag. + + +### Key concepts + +#### Authentication + +All X API v2 endpoints require for you to authenticate your requests with a set of credentials, also known as keys and tokens. + +You can use either OAuth 1.0a User Context or OAuth 2.0 Bearer Token to authenticate your requests to the Retweets lookup endpoint. + +The manage Retweets endpoints require the use of OAuth 1.0a User Context, which means that you must use a set of API keys and user access tokens to make a successful request. The access tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of access tokens for another user, they must authorize or authenticate your App using the 3-legged OAuth flow. + +Please note that OAuth 1.0a can be tricky to use. If you are not familiar with this authentication method, we recommend that you use a [library](/tools-and-libraries) to properly authenticate your requests. + +**Please note** + +If you are requesting the following fields, OAuth 1.0a User Context is required: + +* tweet.fields.non\_public\_metrics +* tweet.fields.promoted_metrics +* tweet.fields.organic_metrics +* media.fields.non\_public\_metrics +* media.fields.promoted_metrics +* media.fields.organic_metrics + +#### Developer Console, Projects, and developer Apps + +To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must [sign up for a developer account](https://developer.x.com/en/portal/petition/essential/basic-info), set up a [Project](/resources/fundamentals/developer-apps) within that account, and created a [developer App](/resources/fundamentals/developer-apps) within that Project. You can then find your keys and tokens within your developer App. + + +#### Rate limits + +Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, [rate limits](/x-api/fundamentals/rate-limits) are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. + +The manage Retweets endpoints are limited to 50 requests per 15 min (per user). Additionally, for the POST endpoint, you are limited to 300 requests per 3-hour window (per user, per app). + +With the Retweets lookup endpoint, you are limited to 75 requests per 15-min window. Additionally, only the 100 most recent Retweeting users will be returned by this endpoint. + +#### Fields and expansions + +The X API v2 allows users to select exactly which data they want to return from the API using a set of tools called fields and expansions. The expansion parameter allows you to expand objects referenced in the payload. For example, this endpoint allows you to pull the following [expansions](/x-api/fundamentals/expansions): + +* attachments.poll_ids +* attachments.media_keys +* author_id, entities.mentions.username +* geo.place_id +* in\_reply\_to\_user\_id, +* referenced_tweets.id, +* referenced\_tweets.id.author\_id + + +The fields parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. These endpoints delivers Post objects primarily. By default, the Post object returns the id and text fields. To receive additional fields such as tweet.created_at or tweet.entities, you will have to specifically request those using a fields parameter. Some important fields that you may want to consider using in your integration are our poll data, metrics, Post annotations, and conversation ID fields. + +We've added a guide on how to [use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). + +--- + +### Code examples + +#### Get users who retweeted a Post + + + +```bash cURL +curl "https://api.x.com/2/tweets/1234567890/retweeted_by?user.fields=username,verified" \ + -H "Authorization: Bearer $BEARER_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_BEARER_TOKEN") + +# Get users who retweeted a Post +response = client.posts.get_retweeted_by( + "1234567890", + user_fields=["username", "verified"] +) +for user in response.data: + print(f"{user.username} - Verified: {user.verified}") +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); + +// Get users who retweeted a Post +const response = await client.posts.getRetweetedBy("1234567890", { + userFields: ["username", "verified"], +}); + +response.data?.forEach((user) => { + console.log(`${user.username} - Verified: ${user.verified}`); +}); +``` + + + +#### Retweet a Post + + + +```bash cURL +curl -X POST "https://api.x.com/2/users/123/retweets" \ + -H "Authorization: OAuth ..." \ + -H "Content-Type: application/json" \ + -d '{"tweet_id": "1234567890"}' +``` + +```python Python SDK +from xdk import Client +from xdk.oauth1_auth import OAuth1 + +oauth1 = OAuth1( + api_key="YOUR_API_KEY", + api_secret="YOUR_API_SECRET", + access_token="YOUR_ACCESS_TOKEN", + access_token_secret="YOUR_ACCESS_TOKEN_SECRET" +) + +client = Client(auth=oauth1) + +# Retweet a Post +response = client.posts.retweet(user_id="123", tweet_id="1234567890") +print(response.data) +``` + +```javascript JavaScript SDK +import { Client, OAuth1 } from "@xdevplatform/xdk"; + +const oauth1 = new OAuth1({ + apiKey: "YOUR_API_KEY", + apiSecret: "YOUR_API_SECRET", + accessToken: "YOUR_ACCESS_TOKEN", + accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", +}); + +const client = new Client({ oauth1 }); + +// Retweet a Post +const response = await client.posts.retweet("123", { tweetId: "1234567890" }); +console.log(response.data); +``` + + diff --git a/x-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.mdx b/x-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.mdx index 6a9dcdb3b..88fe1ab9e 100644 --- a/x-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.mdx +++ b/x-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.mdx @@ -1,184 +1,36 @@ ---- -title: Manage Retweets -sidebarTitle: Manage Retweets -keywords: ["manage retweets migration", "v1.1 to v2 manage retweets", "migrate manage retweets", "standard to v2 retweets", "retweets migration"] ---- - -### Manage Retweets: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST statuses/retweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id), and [POST statuses/unretweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-unretweet-id)  endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 Retweets endpoints. - -* **Similarities** - * Authentication -* **Differences** - * Endpoint URLs and HTTP methods - * Request limitations - * App and Project requirements - * Request parameters - -#### Similarities - -**Authentication** - -Both the standard v1.1 and X API v2 manage Retweets ([POST statuses/retweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id), and [POST statuses/unretweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-unretweet-id)) endpoints use [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 Retweets lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.  - -#### Differences - -**Endpoint URLs and HTTP methods** - -* Standard v1.1 endpoints: - * https://api.x.com/1.1/statuses/retweet/:id.json - (Retweets a Post. Returns the original Post with Retweet details embedded) - * https://api.x.com/1.1/statuses/unretweet/:id.json - (Undo a Retweet. Returns the original Post with Retweet details embedded) -* X API v2 endpoint: - * https://api.x.com/2/tweets/:id/retweets - (Retweets a given Post) - * https://api.x.com/2/users/:id/retweets/:source\_tweet\_id - (Undo a Retweet of a given Post)  - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App. - - -**Request parameters** - -The following standard v1.1 request parameters accepted two request query parameters (user\_id or screen\_name). The X API v2 only accepts the numerical user ID, and it must be passed as part of the endpoint path. - -| Standard v1.1 | X API v2 | -| :--- | :--- | -| **id** | **id** | -| **includes_entities** | No equivalent | - -Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters for the POST endpoint or path parameters for the DELETE endpoint. - -Also, an id of the user Retweeting a Post is not required when using the standard v1.1 endpoints since the [Access Tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) passed with [OAuth 1.0a User Context](/resources/fundamentals/authentication) infer which user is initiating the Retweet/undoing a Retweet. - ---- - -## Code examples - -### Retweet a Post (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123456789/retweets" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"tweet_id": "1234567890"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/retweets" -response = requests.post(url, auth=auth, json={"tweet_id": "1234567890"}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Retweet a Post -response = client.posts.retweet(user_id="123456789", tweet_id="1234567890") -print(f"Retweeted: {response.data.retweeted}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Retweet a Post -const response = await client.posts.retweet("123456789", { tweetId: "1234567890" }); -console.log(`Retweeted: ${response.data?.retweeted}`); -``` - - - -### Undo a Retweet (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/users/123456789/retweets/1234567890" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/retweets/1234567890" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Undo a Retweet -response = client.posts.unretweet(user_id="123456789", tweet_id="1234567890") -print(f"Retweeted: {response.data.retweeted}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Undo a Retweet -const response = await client.posts.unretweet("123456789", "1234567890"); -console.log(`Retweeted: ${response.data?.retweeted}`); -``` - - +--- +title: Manage Retweets +sidebarTitle: Manage Retweets +keywords: ["manage retweets migration", "v1.1 to v2 manage retweets", "migrate manage retweets", "standard to v2 retweets", "retweets migration"] + + +--- +### Manage Retweets: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST statuses/retweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id), and [POST statuses/unretweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-unretweet-id)  endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 Retweets endpoints. + +* **Similarities** + * Authentication +* **Differences** + * Endpoint URLs and HTTP methods + * Request limitations + * App and Project requirements + * Request parameters + +#### Similarities + +**Authentication** + +Both the standard v1.1 and X API v2 manage Retweets ([POST statuses/retweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id), and [POST statuses/unretweet/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-unretweet-id)) endpoints use [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 Retweets lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.  + +#### Differences + +**Endpoint URLs and HTTP methods** + +* Standard v1.1 endpoints: + * https://api.x.com/1.1/statuses/retweet/:id.json + (Retweets a Post. Returns the original Post with Retweet details embedded) + * https://api.x.com/1.1/statuses/unretweet/:id.json + (Undo a Retweet. Returns the original Post with Retweet details embedded) +* X API v2 endpoint: + \ No newline at end of file diff --git a/x-api/posts/retweets/migrate/overview.mdx b/x-api/posts/retweets/migrate/overview.mdx index 8a570e4b9..a1d51d3a0 100644 --- a/x-api/posts/retweets/migrate/overview.mdx +++ b/x-api/posts/retweets/migrate/overview.mdx @@ -1,60 +1,60 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["retweets migration", "retweets migrate", "v1.1 to v2 retweets", "retweets migration guide", "migrate retweets"] ---- - -## Comparing X API’s Retweets endpoints - -**Retweets lookup** - -The v2 Retweets lookup endpoint will replace the standard [v1.1 GET statuses/retweets/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets-id) and [v1.1 GET statuses/retweets/:ids](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids) endpoints. - -The following tables compare the standard v1.1 and X API v2 Retweets endpoints: - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | GET | GET | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/retweeters/id.json

`/1.1/retweets/ids.json` | /2/users/:id/retweeted_by | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 2.0 Bearer Token

OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min | 75 requests per 15 min (per App)

75 requests per 15 min (per user) | -| Data format | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | - -### Manage Retweets - -The following tables compare the standard v1.1 and X API v2 undo Retweet endpoint: - -**Retweet a Post** - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | POST | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/statuses/retweet/:id.json | /2/users/:id/retweets | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | None

300 requests per 3-hour window (per user, per app). This is shared with the POST Tweet endpoint | 50 requests per 15 min (per user)

300 requests per 3-hour window (per user, per app). This is shared with the POST Tweet endpoint for manage Posts. | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | - -#### Undo a Retweet - -The following tables compare the standard v1.1 and X API v2 undo Retweet endpoint: - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | DELETE | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/statuses/unretweet/:id.json | /2/users/:id/retweets/:source\_tweet\_id | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | -| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 50 requests per 15 min (per user) | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | - -**Other migration resources** - -[Retweets lookup: Standard v1.1 to X API v2](/x-api/posts/retweets#retweets-lookup-standard-v1-1-compared-to-x-api-v2 "Retweets lookup: Standard v1.1 to X API v2") - -[Manage Retweets: Standard v1.1 to X API v2](/x-api/posts/retweets#manage-retweets-standard-v1-1-compared-to-x-api-v2) - -[X API migration hub](/x-api/migrate/overview) - +--- +title: Overview +sidebarTitle: Overview +keywords: ["retweets migration", "retweets migrate", "v1.1 to v2 retweets", "retweets migration guide", "migrate retweets"] + + +## Comparing X API’s Retweets endpoints + +**Retweets lookup** + +The v2 Retweets lookup endpoint will replace the standard [v1.1 GET statuses/retweets/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets-id) and [v1.1 GET statuses/retweets/:ids](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids) endpoints. + +The following tables compare the standard v1.1 and X API v2 Retweets endpoints: + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | GET | GET | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/retweeters/id.json

`/1.1/retweets/ids.json` | /2/users/:id/retweeted_by | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 2.0 Bearer Token

OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 75 requests per 15 min | 75 requests per 15 min (per App)

75 requests per 15 min (per user) | +| Data format | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | +| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | + +### Manage Retweets + +The following tables compare the standard v1.1 and X API v2 undo Retweet endpoint: + +**Retweet a Post** + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | POST | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/statuses/retweet/:id.json | /2/users/:id/retweets | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | None

300 requests per 3-hour window (per user, per app). This is shared with the POST Tweet endpoint | 50 requests per 15 min (per user)

300 requests per 3-hour window (per user, per app). This is shared with the POST Tweet endpoint for manage Posts. | +| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | + +#### Undo a Retweet + +The following tables compare the standard v1.1 and X API v2 undo Retweet endpoint: + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | DELETE | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/statuses/unretweet/:id.json | /2/users/:id/retweets/:source\_tweet\_id | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context | +| Default request [rate limits](/resources/fundamentals/rate-limits) | None | 50 requests per 15 min (per user) | +| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | + +**Other migration resources** + +[Retweets lookup: Standard v1.1 to X API v2](/x-api/posts/retweets#retweets-lookup-standard-v1-1-compared-to-x-api-v2 "Retweets lookup: Standard v1.1 to X API v2") + +[Manage Retweets: Standard v1.1 to X API v2](/x-api/posts/retweets#manage-retweets-standard-v1-1-compared-to-x-api-v2) + +[X API migration hub](/x-api/migrate/overview) + diff --git a/x-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.mdx b/x-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.mdx index 9fb4816c7..6b65d0f0e 100644 --- a/x-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.mdx +++ b/x-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.mdx @@ -1,137 +1,39 @@ ---- -title: Retweets lookup -sidebarTitle: Retweets lookup -keywords: ["retweets lookup migration", "v1.1 to v2 retweets lookup", "migrate retweets lookup", "standard to v2 retweets", "retweets migration"] ---- - -### Retweets lookup: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [v1.1 GET statuses/retweets/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets-id), [v1.1 GET statuses/retweets/:ids](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids), the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 Retweets lookup endpoints. - -* **Similarities** - * Authentiation - * Users per request limits -* **Differences** - * Endpoint URLs - - * Request limitations - * App and Project requirements - - * Response data format - * Request parameters - -#### Similarities - -**Authentication** - -Both the standard v1.1 and X API v2 Retweets lookup endpoints ([v1.1 GET statuses/retweets/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets-id) and [v1.1 GET statuses/retweeters/:ids](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids)) use [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication) or OAuth 2.0 Bearer Token. - -**Users per request limits** - -For both v1.1 and v2 GET endpoints the max number of users that will be returned by the Retweets lookup endpoint is 100 users. For the v2 Retweets lookup endpoint, there is no pagination token being passed, by default we give out 100 users and that's the max that is returned. - -#### Differences -**Endpoint URLs** - -* Standard v1.1 endpoints: - * https://api.x.com/1.1/statuses/retweets/:id.json - (Returns a collection of the 100 most recent Retweets of the Post specified by the `id` parameter) - * `https://api.x.com/1.1/statuses/retweeters/ids.json` - (Returns a collection of up to 100 user IDs belonging to users who have Retweeted the Post specified by the `id` parameter) -* X API v2 endpoint: - * https://api.x.com/2/tweets/:id/retweeted_by - (Returns a list of accounts who have Retweeted a given Post) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the user id , name, and username fields by default. To request any additional fields or objects, you wil need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any user fields that you request from this endpoint will return in the primary user object. Any expanded Post object and fields will return in an includes object within your response. You can then match any expanded objects back to the user object by matching the IDs located in both the user and the expanded Post object.  - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.  -   - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - -**Request parameters** - -The following standard v1.1 request parameters accepted two request query parameters (user_id or screen_name). The X API v2 only accepts the numerical user ID, and it must be passed as part of the endpoint path. - ---- - -## Code examples - -### Get users who Retweeted a Post (v2) - - - -```bash cURL -curl "https://api.x.com/2/tweets/1234567890/retweeted_by?user.fields=username,verified" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/1234567890/retweeted_by" - -params = {"user.fields": "username,verified"} -headers = {"Authorization": f"Bearer {bearer_token}"} - -response = requests.get(url, headers=headers, params=params) -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get users who Retweeted a Post -response = client.posts.get_retweeted_by( - "1234567890", - user_fields=["username", "verified"] -) -for user in response.data: - print(f"{user.username} - Verified: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get users who Retweeted a Post -const response = await client.posts.getRetweetedBy("1234567890", { - userFields: ["username", "verified"], -}); - -response.data?.forEach((user) => { - console.log(`${user.username} - Verified: ${user.verified}`); -}); -``` - - +--- +title: Retweets lookup +sidebarTitle: Retweets lookup +keywords: ["retweets lookup migration", "v1.1 to v2 retweets lookup", "migrate retweets lookup", "standard to v2 retweets", "retweets migration"] + + +--- +### Retweets lookup: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [v1.1 GET statuses/retweets/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets-id), [v1.1 GET statuses/retweets/:ids](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids), the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 Retweets lookup endpoints. + +* **Similarities** + * Authentiation + * Users per request limits +* **Differences** + * Endpoint URLs + + * Request limitations + * App and Project requirements + + * Response data format + * Request parameters + +#### Similarities + +**Authentication** + +Both the standard v1.1 and X API v2 Retweets lookup endpoints ([v1.1 GET statuses/retweets/:id](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets-id) and [v1.1 GET statuses/retweeters/:ids](https://developer.x.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids)) use [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication) or OAuth 2.0 Bearer Token. + +**Users per request limits** + +For both v1.1 and v2 GET endpoints the max number of users that will be returned by the Retweets lookup endpoint is 100 users. For the v2 Retweets lookup endpoint, there is no pagination token being passed, by default we give out 100 users and that's the max that is returned. + +#### Differences +**Endpoint URLs** + +* Standard v1.1 endpoints: + * https://api.x.com/1.1/statuses/retweets/:id.json + (Returns a collection of the 100 most recent \ No newline at end of file diff --git a/x-api/posts/search-all-posts.mdx b/x-api/posts/search-all-posts.mdx index 5b3db39b0..7f05b4462 100644 --- a/x-api/posts/search-all-posts.mdx +++ b/x-api/posts/search-all-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/all ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/search-recent-posts.mdx b/x-api/posts/search-recent-posts.mdx index 8559b1759..738cce63d 100644 --- a/x-api/posts/search-recent-posts.mdx +++ b/x-api/posts/search-recent-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/recent ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/posts/search/integrate/paginate.mdx b/x-api/posts/search/integrate/paginate.mdx index 669d56870..1f280737d 100644 --- a/x-api/posts/search/integrate/paginate.mdx +++ b/x-api/posts/search/integrate/paginate.mdx @@ -2,7 +2,8 @@ title: Pagination sidebarTitle: Pagination keywords: ["search pagination", "pagination guide", "page through results", "pagination tokens", "search pagination", "next token"] ---- + +description: Search queries typically match on more Posts than can be returned in a single API response. When that happens, the data is returned in a series of 'pages'.--- ### Recent search pagination diff --git a/x-api/posts/search/introduction.mdx b/x-api/posts/search/introduction.mdx index 20095322e..7870cad1b 100644 --- a/x-api/posts/search/introduction.mdx +++ b/x-api/posts/search/introduction.mdx @@ -1,7 +1,7 @@ --- title: Search Posts sidebarTitle: Introduction -description: Search for Posts by keyword, hashtag, user, and more with powerful query operators +description: Search the full X archive or recent Posts using advanced operators for keywords, hashtags, users, geo, language, engagement metrics, and more. Supports both 7-day recent search and full-archive historical search. keywords: ["search tweets", "search posts", "recent search", "full archive search", "tweet search", "search API", "search queries", "search operators", "historical search"] --- diff --git a/x-api/posts/search/migrate/enterprise-to-twitter-api-v2.mdx b/x-api/posts/search/migrate/enterprise-to-twitter-api-v2.mdx index 90fbd67cf..12b132867 100644 --- a/x-api/posts/search/migrate/enterprise-to-twitter-api-v2.mdx +++ b/x-api/posts/search/migrate/enterprise-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 (Enterprise) sidebarTitle: v1 to v2 (Enterprise) keywords: ["enterprise to v2", "enterprise migration", "GNIP to v2", "enterprise search migration", "migrate enterprise", "v1 to v2 enterprise"] ---- + +--- ### Enterprise compared to X API v2 @@ -58,77 +59,4 @@ The X API v2 endpoints require that you use credentials from a Project when auth **Available time periods** -Both the enterprise API and X API v2 offer endpoints that allow you to retrieve filtered Post data for the full-archive of Posts. - -However, the X API v2 does not offer a 30 day time period endpoint like the enterprise API does. Instead it offers the aforementioned full-archive, or a 7 day time period, which align with the Native Enriched to v2 and [Activity Streams to v2](/x-api/migrate/data-format-migration#migrating-from-activity-streams-data-format-to-v2) which can help you map enterprise fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. -  - -**Response data format** - -One of the biggest differences between the [enterprise response format](https://developer.x.com/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary) and[X API v2’s format](/x-api/fundamentals/data-dictionary) is how you select which fields return in your payload. - -For the enterprise Search API, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the Post `id` and `text` fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any Post fields that you request from these endpoints will return in the primary Post object. Any expanded user, media, poll, or place objects and fields will return in an `includes` object within your response. You can then match any expanded objects back to the Post object by matching the IDs located in both the Post and the expanded object. - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a `statuses` array, while X API v2 returns a `data` array. -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as `contributors` and `user.translator_type` are being removed. -* Instead of using both `favorites` (in Post object) and `favourites` (in user object), X API v2 uses the term like. -* X is adopting the convention that JSON values with no value (for example, `null`) are not written to the payload. Post and user attributes are only included if they have non-null values. -   - -We also introduced a new set of fields to the Post object including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields -* A new `reply_setting` field, which shows you who can reply to a given Post - -And one last note. The premium response includes a `requestParameters` object at the root level, which contains the parameters that you included in your request. The v2 version instead contains a `meta` object that lives at the root level which includes the `newest_id`, `oldest_id`, `result_count`, and `next_token` if there is an additional page of results. - -**HTTP methods** - -The enterprise version of the API allows you to pass the request as either a POST HTTP method with a JSON body, or a GET HTTP method with a query string. - -V2 only allows you to use the GET HTTP method with a query string. -  - -**Request time formats** - -The enterprise version of this endpoint uses the following date/time format in both the pagination parameters and the `timePeriod` response field: `YYYYMMDDHHmm` - -The v2 endpoint uses ISO 8601/RFC 3339 date/time format in both the pagination parameters and the `start` and `end` response fields: `YYYY-MM-DDTHH:mm:ssZ - ` - -**Request parameters** - -The following is a table of the request parameters for enterprise and X API v2: - -| Enterprise | Search Posts v2 | -| :--- | :--- | -| query | query | -| maxResults | max_results | -| fromDate (YYMMDDHHmm) | start_time (YYYY-MM-DDTHH:mm:ssZ) | -| toDate (YYMMDDHHmm) | end_time (YYYY-MM-DDTHH:mm:ssZ) | -| | since_id | -| | until_id | -| next | next_token or pagination_token | - -**Filtering operators** - -While the operators between enterprise and X API v2 are mostly the same, there are some differences in operator availability and some new operators that were introduced to just the X API v2 version. - -To see a full table of the operators that are available for X API v2, enterprise, and even premium and standard, please visit the [Search Posts migration landing page](/x-api/posts/search/migrate/overview). - -**Next steps** - -[Check out our quick start guide for X API v2 full-archive search](/x-api/posts/search/quickstart/full-archive-search) - -[Review the API reference for full-archive search](/x-api/posts/full-archive-search) - -[Check out some sample code for these endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code) - +Both \ No newline at end of file diff --git a/x-api/posts/search/migrate/overview.mdx b/x-api/posts/search/migrate/overview.mdx index 07916c784..9b51a9a5a 100644 --- a/x-api/posts/search/migrate/overview.mdx +++ b/x-api/posts/search/migrate/overview.mdx @@ -4,6 +4,7 @@ sidebarTitle: Overview keywords: ["search migration", "search migrate", "v1.1 to v2 search", "search migration guide", "migrate search", "enterprise to v2"] --- + ## Comparing X API's Search Posts endpoints The v2 Search Tweets endpoint will eventually replace the [standard v1.1 search/posts](/x-api/posts/search/introduction) endpoint and [enterprise Search API](/x-api/enterprise-gnip-2.0/fundamentals/search-api). If you have code, apps, or tools that use an older version of a X search endpoint and are considering migrating to the newer X API v2 endpoints, then this guide is for you. diff --git a/x-api/posts/search/migrate/standard-to-twitter-api-v2.mdx b/x-api/posts/search/migrate/standard-to-twitter-api-v2.mdx index 4dd97955f..0b35298b9 100644 --- a/x-api/posts/search/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/posts/search/migrate/standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "search migration", "migrate search", "standard to v2 search", "v1 to v2 search", "migration guide"] ---- + +--- ### Standard v1.1 compared to X API v2 If you have been working with the v1.1 [search/posts](/x-api/posts/search/introduction), the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 search Posts endpoint. @@ -35,212 +36,4 @@ If you would like to take advantage of the ability to pull private or advertisin **Support for Post edit history and metadata** -Both versions provide metadata that describes any edit history. Check out the [search API References](/x-api/posts/recent-search) and the [Post edits fundamentals page](/x-api/fundamentals/edit-posts) for more details.  - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * https://api.x.com/1.1/search/tweets - -* X API v2 endpoint: - * https://api.x.com/2/tweets/search/recent -   - - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with an App.  - - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any Post fields that you request from these endpoints will return in the primary Post object. Any expanded user, media, poll, or place objects and fields will return in an includes object within your response. You can then match any expanded objects back to the Post object by matching the IDs located in both the Post and the expanded object.  - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have non-null values.  -   - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - -#### Request parameters - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard search v1.1 | Search Posts v2 | -| :--- | :--- | -| q | query | -| | start_time (YYYY-MM-DDTHH:mm:ssZ) | -| until (YYYY-MM-DD) | end_time (YYYY-MM-DDTHH:mm:ssZ) | -| since_id | since_id | -| max_id | until_id | -| count | max_results | -| Response provides search\_metadata.next\_results | next_token | - -There are also a set of standard search Posts request parameters **not** supported in X API v2: - -| **Standard v1.1 parameter** | **Details** | -| :--- | :--- | -| geocode | Search Posts supports geo operators for location-based queries. | -| locale | With standard search, this was used to specify the language of the query but never fully implemented. | -| lang | Search Posts endpoints provide a lang query operator for matching on languages of interest. | -| include_entities | Post entities are always included. | -| result_type | Search Posts endpoints deliver all matching Posts, regardless of engagement level. | -| extended | X API v2 is built from the ground up to support Posts with up to 280 characters. With v2, there is no concept of 'extended' Posts. | - - -Here is an example request that shows the difference between a Standard request and a Search Posts request: - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| https://api.x.com/1.1/search/tweets.json?q=snow&count=50 | https://api.x.com/2/tweets/search/recent?query=snow&max_results=50 | - - -These requests will both return the 50 most recent Posts that contain the keyword snow. The v2 request will return the default id and text fields of the matching Posts. Here is an example of specifying additional Posts and user fields to include in the JSON payload: - -| | -| :--- | -| **X API v2** | -| https://api.x.com/2/tweets/search/recent?query=snow&max\_results=50&tweet.fields=id,created\_at,author_id,text,source,entities,attachments&user.fields=id,name,username,description | - -**New query operators** - -Search Posts introduces new operators in support of two new X API v2 features:  - -* **[Conversation IDs](/x-api/fundamentals/conversation-id)** \- As conversations unfold on X, a conservation ID will be available to mark Posts that are part of the conversation. All Posts in the conversation will have their conversation_id set to the Post ID that started it.  - * `conversation_id:` -* **[X Annotations](/x-api/fundamentals/post-annotations)** provide contextual information about Posts, and include entity and context annotations. Entities are comprised of people, places, products and organizations. Contexts are domains, or topics, that surfaced entities are a part of. For example, people mentioned in a Post may have a context that indicates whether they are an athlete, actor, or politician.   - * context: matches on Posts that have been annotated with a context of interest.  - * entity: matches on Posts that have been annotated with an entity of interest.  - -   - -#### AND / OR operator precedence  - -The basic building block for building search queries is the use of OR and AND logical groupings. The standard search API applies ORs before ANDs, while Search Posts endpoints (as well as the premium and enterprise versions) applies ANDs before ORs. This difference is critical when translating queries between the two.  - -For example, with standard search, if you wanted to match Posts with the keyword ‘storm’ that mention the word ‘colorado’ or the #COwx hashtag, you could do that with the following search query: - -storm #COwx OR colorado - -With the Search Posts operator precedence, ANDs are applied before ORs. So the above query is equivalent to:  - -(storm #COwx) OR colorado - -However, the above rule would match on any Posts that mentions ‘Colorado’, regardless if the Post mentions ‘storm’ or the #COwx hashtag. In addition it would also  match Posts that mentioned both the keyword ‘storm’ and the #COwx hashtag.  - -To make the query behave as originally intended, the OR clauses need to be grouped together. The translation of the original standard query to Search Posts would be: - -storm (#COwx OR colorado) - -These two rules have very different matching behavior. For the month of October 2019, the original rule matches over 1,175,000 Posts while the correctly translated rule matches around 5,600 Posts. Be sure to mind your ANDs and ORs, and use parentheses where needed.  - - -#### cURL requests - -**The following section displays cURL requests for the standard v1.1 endpoint and its equivalent endpoint in v2.** - -The requests are made using [OAuth 2.0 App-Only](https://developer.x.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token). In order to run the following cURL requests, you will need to replace ACCESS_TOKEN in the authorization header with your app access token. For v2 endpoints, your app access token must belong to a [developer App](/resources/fundamentals/developer-apps/overview) within a [Project](/resources/fundamentals/developer-apps/overview).  - -The response payload returned by the v1.1 endpoint will be different from the response payload returned by the v2 endpoint. With v2, the response will include the default fields, as well as any other fields requested with the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. You can use these parameters to request a different set of fields to be returned. - -**Standard v1.1 `GET search/tweets` → v2 `GET tweets/search/recent`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/search/tweets.json?q=from%3AXDevelopers%20-is%3Aretweet&count=100' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/tweets/search/recent?query=from%3AXDevelopers%20-is%3Aretweet&tweet.fields=created_at%2Cconversation_id%2Centities&max_results=100' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/tweets/search/recent" - -params = { - "query": "from:XDevelopers -is:retweet", - "tweet.fields": "created_at,conversation_id,entities", - "max_results": 100 -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -for post in response.json()["data"]: - print(f"{post['created_at']}: {post['text'][:50]}...") -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Search recent Posts - SDK handles pagination automatically -for page in client.posts.search_recent( - query="from:XDevelopers -is:retweet", - tweet_fields=["created_at", "conversation_id", "entities"], - max_results=100 -): - for post in page.data: - print(f"{post.created_at}: {post.text[:50]}...") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Search recent Posts - SDK handles pagination automatically -const paginator = client.posts.searchRecent("from:XDevelopers -is:retweet", { - tweetFields: ["created_at", "conversation_id", "entities"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`); - }); -} -``` - - - -**Next steps** - -[Check out our quick start guide for X API v2 recent search](/x-api/posts/search/quickstart/recent-search) - -[Review the API reference for recent search](/x-api/posts/recent-search) - -[Check out some sample code for these endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code "Check out some sample code for these endpoints") - -[Step-by-step guide to making your first request to recent search](/x-api/getting-started/make-your-first-request "Step-by-step guide to making your first request to recent search") - +Both versions provide metadata that describes any edit history. Check out the [search API References]( \ No newline at end of file diff --git a/x-api/posts/timelines/integrate.mdx b/x-api/posts/timelines/integrate.mdx index 740863c34..4030873af 100644 --- a/x-api/posts/timelines/integrate.mdx +++ b/x-api/posts/timelines/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating Timelines endpoints keywords: ["timeline integration", "timeline guide", "timeline implementation", "home timeline integration", "user timeline integration"] --- diff --git a/x-api/posts/timelines/migrate/overview.mdx b/x-api/posts/timelines/migrate/overview.mdx index a61dd05c0..e506e4baf 100644 --- a/x-api/posts/timelines/migrate/overview.mdx +++ b/x-api/posts/timelines/migrate/overview.mdx @@ -2,7 +2,7 @@ title: Overview sidebarTitle: Overview keywords: ["timeline migration", "timeline migrate", "v1.1 to v2 timeline", "timeline migration guide", "migrate timeline"] ---- + ## Comparing X API's timelines endpoints @@ -94,15 +94,4 @@ The following tables compare the standard v1.1 and X API v2 user mention timelin | Optional parameters for results refinement | count
trim_user
include_entities
tweet_mode
since_id
max_id | max_results
tweet.fields
user.fields
place.fields
media.fields
poll.fields
expansions
start_time
end_time
since_id
until_id | | Supports requesting and receiving [annotations](/x-api/fundamentals/post-annotations) | N/A | Returns Posts results with inferred anotation data based on the Post text, such as 'Music Genre' and 'Folk Music' or 'Musician' and 'Dolly Parton' | | Supports requesting and receiving specific Post [metrics](/x-api/fundamentals/metrics) | N/A | Returns Post results with available public_metrics per Post including retweet_count, reply_count, quote_count and like_count.

Available with OAuth 1.0a User Context:
Additional non\_public\_metrics , including impression_count, user\_profile\_clicks, url\_link\_clicks.

Additional media metrics such as view_count and video playback metrics.

Additional organic_metrics and promoted_metrics available with OAuth 1.0a User Context for promoted Posts | -| Supports requesting and receiving [conversation_id](/x-api/fundamentals/conversation-id) | N/A | Returns a conversation_id field where the value represents the first published Post in a reply thread to help you track conversations. | -| Post JSON format | [Standard v1.1 data format](/x-api/fundamentals/data-dictionary) | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | -| Results order | Reverse chronological | Reverse chronological | -| Request parameters for pagination | N/A must use navigation by Post ID | Results can be reviewed moving forward or backward using pagination_token | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [Project](/resources/fundamentals/developer-apps) | | ✔ | -| Provides Post edit history | ✔ | ✔ | - -**Other migration resources** - -[Post lookup: Standard v1.1 to X API v2](/x-api/posts/lookup/migrate/standard-to-twitter-api-v2 "Post lookup: Standard v1.1 to X API v2") - -[X API migration hub](/x-api/migrate/overview) +| \ No newline at end of file diff --git a/x-api/posts/timelines/migrate/standard-to-twitter-api-v2.mdx b/x-api/posts/timelines/migrate/standard-to-twitter-api-v2.mdx index 9bfa2e028..88c9d3336 100644 --- a/x-api/posts/timelines/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/posts/timelines/migrate/standard-to-twitter-api-v2.mdx @@ -2,8 +2,9 @@ title: v1 to v2 sidebarTitle: v1 to v2 keywords: ["v1.1 to v2 migration", "timeline migration", "migrate timeline", "standard to v2 timeline", "v1 to v2 timeline", "migration guide"] ---- + +--- import { Button } from '/snippets/button.mdx'; ## Standard v1.1 timelines to X API v2 timelines @@ -33,224 +34,4 @@ If you have been working with the v1.1 timelines endpoints (statuses/user\_timel * Different max_results (count) per response * Response data format * Request parameters - * Customized data format based on request parameters, including v2 fields and expansions - * Additional available data: metrics, Post annotations, polls - -### Similarities - -**Authentication** - -The v1.1 statuses/user_timeline and the X API v2 user Post timeline endpoint support both [OAuth 1.0a User Context](/resources/fundamentals/authentication) and [OAuth 2.0 App-Only](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). Therefore, you can continue using the same authentication method and authorization tokens if you migrate to the X API v2 version. - -**Historical Access** - -The v1.1 statuses/user_timeline and the X API v2 user Post timeline endpoint both will return the most recent 3200 Posts, including Retweets - -The v1.1 statuses/mentions_timeline and the X API v2 user mention timeline endpoint can return the most recent 800 Posts. - -**Support for Post edit history and metadata** - -Both versions provide metadata that describes any edit history. Check out the [filtered stream API References](/x-api/posts/filtered-stream/introduction) and the [Edit Posts fundamentals page](/x-api/fundamentals/edit-posts) for more details. - -**Rate Limits** - -| | | -| :--- | :--- | -| **Standard v1.1** | **X API v2** | -| user_timeline:

900 requests per 15 min with OAuth 1.0a User Context

1500 requests per 15 min with OAuth 2.0 App-Only | User Posts timeline:

900 requests per 15-minute window with OAuth 1.0a User Context

1500 requests per 15-minute window with OAuth 2.0 App-Only | - -**Refresh polling using since_id** - -Both versions allow polling for recent results using the since_id. - -**Traversing timelines by Post IDs** - -Both endpoints have the capability to traverse through timelines using Post ID 'timestamps' based on the way Post IDs are constructed. The functionality is generally the same except for the following: - -| | | -| :--- | :--- | -| **Standard timelines v1.1** | **timelines v2** | -| since_id (exclusive)

max_id (inclusive) | since_id (exclusive)

until_id (also exclusive, vs max_id which was inclusive) | - -**Response filtering parameters** - -| | | -| :--- | :--- | -| **Standard timelines v1.1** | **timelines v2** | -| Response filtering parameters:

* include_rts
* exclude_replies | Response filtering parameters:

* exclude=retweets,replies | -| Example

https://api.x.com/1.1/statuses/user\_timeline.json?user\_id=2244994945&include\_rts=0&&exclude\_replies=1 | Example:

https://api.x.com/2/users/2244994945/tweets?max_results=100&exclude=retweets,replies | -| Notes:

For user_timeline:

* Using include_rts=0 does not change the possible historical Post limit of the most recent 3200 | Notes:

For user Posts timeline:

* Using exclude=retweets does not change the possible historical Post limit of the most recent 3200
* Using exclude=replies reduces the possible historical Post limit to the most recent 800 replies | - -### Differences - -**Authentication** - -**The v1.1 statuses/mentions_timeline endpoint only supports [OAuth 1.0a User Context](https://developer-staging.x.com/resources/fundamentals/authentication). The X API v2 user mention timeline endpoint supports both [OAuth 1.0a User Context](/resources/fundamentals/authentication),[OAuth 2.0 App-Only](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only), and [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authenticationoauth-2-0/authorization-code "This method allows an authorized app to act on behalf of the user, as the user. It is typically used to access or post public information for a specific user, and it us useful when your app needs to be aware of the relationship between a user and what this endpoint returns. Click to learn how to authenticate with OAuth 2.0 Authorization Code with PKCE.") ** - -If you would like to take advantage of the ability to access private or promoted metrics using the X API v2 user Post timeline endpoint, you will need to use OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, and pass the user access tokens related to the user who posted the Post for which you would like to access metrics. - - -**Endpoint URLs** - -Note that the X API v2 timelines endpoints require a path parameter of :id for the user ID. - -* Standard v1.1 endpoints: - * https://api.x.com/1.1/statuses/home_timeline - * https://api.x.com/1.1/statuses/user_timeline - * https://api.x.com/1.1/statuses/mention_timeline -* X API v2 endpoint: - * https://api.x.com/2/users/:id/timelines/reverse_chronological - * https://api.x.com/2/users/:id/tweets - * https://api.x.com/2/users/:id/mentions - - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Rate Limits** - -| | | -| :--- | :--- | -| **mentions_timeline:**

75 requests per 15 min with OAuth 1.0a User Context | **user mention timeline: **

180 requests per 15-minute window with OAuth 1.0a User Context
450 requests per 15-minute window with OAuth 2.0 Bearer Token | -| **home_timelime:**

15 requests per 15 minutes

Up to 800 Posts are obtainable on the home timeline | **reverse chronological home timeline:**

180 requests per 15 minutes

You can return every Post created on a timeline over the last 7 days as well as the most recent 800 regardless of creation date. | - -**Request parameters** - -| | | -| :--- | :--- | -| **Standard timelines v1.1** | **timelines v2** | -| Required: user_id or screen_name | Required: The specific user ID is specified in the path parameter | -| Optional:

count \- sets the maximum results returned per request

exclude_replies \- removes replies from the results

Include_rts \- when set to 0 removes retweets from the results

trim_user \- removes rehydrated user objects from the results

tweet_mode \- sets the data format returned for the results, set to extended for Posts longer than 140

since_id \- sets the earliest Post ID in result (exclusive)

max_id \- sets the latest Post ID in result (inclusive) | Optional:

max_results \- sets the maximum results returned per request

exclude=retweets,replies \- removes Retweets or replies from the results

tweet.fields \- sets the Post object fields to return

user.fields \- sets the User object fields to return

place.fields \- sets the place object fields to return

media.fields \- sets the media object fields to return

poll.fields \- sets the poll object fields to return

expansions - sets the expanded fields and data to return

start_time \- sets the earliest created_at time for the results

end_time \- sets the latest created_at time for the results

since_id \- sets the earliest Post ID for the results (exclusive)

until_id \- sets the latest Post ID in result (exclusive) | - -**Response data format** - -| | | -| :--- | :--- | -| **Standard search v1.1** | **Search Posts v2** | -| \[
tweet object,
tweet object
\] |
"data": \[id,text,id,text\],
"meta":
"oldest_id": "1337085692623646724",
"newest_id": "1334183616172019713",
"previous_token": "77qpymm88g5h9vqkluldpw91lr0qzfz1sqydh841iz48k",
"result_count": 10,
"next_token": "7140dibdnow9c7btw3w29gqolns6a1ipl3kzeae41vsxk"

| - -**X API v2 JSON format** - -X API v2 is introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. You can learn more about the X API v2 format, how to use fields and expansions by visiting our [guide](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions), and by reading through our broader [data dictionary](/x-api/fundamentals/data-dictionary) - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array. -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. -* Instead of using both favorites (in Post object) and favorites (in user object), X API v2 uses the term like. -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null value. - - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. For the standard endpoints, there are several parameters that you could use to identify which fields or sets of fields would return in the payload, while the X API v2 version simplifies these different parameters into [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions). - -* fields: X API v2 endpoints enable you to select which fields are provided in your payload. For example, Post, user, Media, Place, and Poll objects all have a list of fields that can be returned (or not). -* expansions: Used to expand the complementary objects referenced in Post JSON payloads. For example, all Retweets and Replies reference other Posts. By setting expansions=referenced_tweets.id, these other Post objects are expanded according to the tweet.fields setting. Other objects such as users, polls, and media can be expanded. - -* conversation_id -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields - - -We have put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. - ---- - -## Code examples - -### User Posts timeline (v2) - - - -```bash cURL -curl "https://api.x.com/2/users/2244994945/tweets?max_results=100&tweet.fields=created_at,public_metrics&exclude=retweets,replies" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user's Posts timeline -for page in client.posts.get_user_posts( - "2244994945", - tweet_fields=["created_at", "public_metrics"], - exclude=["retweets", "replies"], - max_results=100 -): - for post in page.data: - print(f"{post.created_at}: {post.text[:50]}...") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get user's Posts timeline -const paginator = client.posts.getUserPosts("2244994945", { - tweetFields: ["created_at", "public_metrics"], - exclude: ["retweets", "replies"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`); - }); -} -``` - - - -### User mentions timeline (v2) - - - -```bash cURL -curl "https://api.x.com/2/users/2244994945/mentions?max_results=100&tweet.fields=created_at,author_id" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user's mentions -for page in client.posts.get_user_mentions( - "2244994945", - tweet_fields=["created_at", "author_id"], - max_results=100 -): - for post in page.data: - print(f"Mentioned by {post.author_id}: {post.text[:50]}...") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get user's mentions -const paginator = client.posts.getUserMentions("2244994945", { - tweetFields: ["created_at", "author_id"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((post) => { - console.log(`Mentioned by ${post.author_id}: ${post.text?.slice(0, 50)}...`); - }); -} -``` - - - -**Next steps** - -[Check out our quick start guide for X API v2 Post lookup](/x-api/posts/lookup/quickstart "Check out our quick start guide for X API v2 Post lookup") - -[Review the API references for v2 Post lookup](/x-api/posts/lookup/migrate/overview "Review the API references for v2 Post lookup") - -[Check out our sample code for the timelines endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code "Check out our sample code for the timelines endpoints") + * Custom \ No newline at end of file diff --git a/x-api/posts/volume-streams/introduction.mdx b/x-api/posts/volume-streams/introduction.mdx index e6ff9241e..dd3534364 100644 --- a/x-api/posts/volume-streams/introduction.mdx +++ b/x-api/posts/volume-streams/introduction.mdx @@ -1,62 +1,63 @@ ---- -title: Introduction -sidebarTitle: Introduction -keywords: ["sampled stream", "1% stream", "10% stream", "decahose", "volume streams", "sampled tweets", "streaming API"] ---- - -import { Button } from '/snippets/button.mdx'; - -* 1% sampled stream. -* 10% sampled stream. Commonly referred to as the "Decahose." - -These are referred to as "volume streams" because they both deliver large volumes of data. Even the 1% stream can emit many dozens of Posts every second. With these streams, you can identify and track trends, monitor general sentiment, monitor global events, and much more.  - -These streaming endpoints deliver [Post objects](/x-api/fundamentals/data-dictionary#tweet) through a persistent HTTP GET connection and use [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) authentication. With Essential access, you can have one connection at a time. With all levels of access, connection requests can be made up to 50 times per 15-minute window. - -These volume stream endpoints support edited Posts. These endpoints will deliver edited Posts, along with its edit history, including an array of Post IDs. For Posts with no edit history, this array will hold a single ID. For Posts that have been edited, this array contains multiple IDs, arranged in ascending order reflecting the order of edits, with the most recent version in the last position of the array. To learn more about how Post edits work, see the [Post edits fundamentals](/x-api/fundamentals/edit-posts) page.  - -_To use these APIs, you must first set up an account with our enterprise sales team._ - - -**Account setup** - -To access these endpoints, you will need: - -* An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info). -* To authenticate using the keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  - -Learn more about getting access to the X API v2 endpoints in our [getting started guide](/x-api/getting-started/getting-access). - -
- - - - -
- ---- - -## Streaming fundamentals - - - - Best practices for streaming clients - - - Reconnect gracefully - - - Handle high throughput - - - Build resilient applications - - +--- +title: Introduction +sidebarTitle: Introduction +keywords: ["sampled stream", "1% stream", "10% stream", "decahose", "volume streams", "sampled tweets", "streaming API"] +--- + + +import { Button } from '/snippets/button.mdx'; + +* 1% sampled stream. +* 10% sampled stream. Commonly referred to as the "Decahose." + +These are referred to as "volume streams" because they both deliver large volumes of data. Even the 1% stream can emit many dozens of Posts every second. With these streams, you can identify and track trends, monitor general sentiment, monitor global events, and much more.  + +These streaming endpoints deliver [Post objects](/x-api/fundamentals/data-dictionary#tweet) through a persistent HTTP GET connection and use [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) authentication. With Essential access, you can have one connection at a time. With all levels of access, connection requests can be made up to 50 times per 15-minute window. + +These volume stream endpoints support edited Posts. These endpoints will deliver edited Posts, along with its edit history, including an array of Post IDs. For Posts with no edit history, this array will hold a single ID. For Posts that have been edited, this array contains multiple IDs, arranged in ascending order reflecting the order of edits, with the most recent version in the last position of the array. To learn more about how Post edits work, see the [Post edits fundamentals](/x-api/fundamentals/edit-posts) page.  + +_To use these APIs, you must first set up an account with our enterprise sales team._ + + +**Account setup** + +To access these endpoints, you will need: + +* An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info). +* To authenticate using the keys and tokens from a [developer App](/resources/fundamentals/developer-apps) that is located within a [Project](/resources/fundamentals/developer-apps).  + +Learn more about getting access to the X API v2 endpoints in our [getting started guide](/x-api/getting-started/getting-access). + +
+ + + + +
+ +--- + +## Streaming fundamentals + + + + Best practices for streaming clients + + + Reconnect gracefully + + + Handle high throughput + + + Build resilient applications + + diff --git a/x-api/powerstream/handling-disconnections.mdx b/x-api/powerstream/handling-disconnections.mdx index 9eb6499e5..90eabeb93 100644 --- a/x-api/powerstream/handling-disconnections.mdx +++ b/x-api/powerstream/handling-disconnections.mdx @@ -4,6 +4,7 @@ sidebarTitle: Handling disconnections keywords: ["powerstream disconnections", "handle disconnections", "reconnect powerstream", "stream disconnections", "powerstream errors"] --- + This page covers Powerstream-specific disconnection handling. For comprehensive guidance on handling disconnections across all streaming endpoints, see the [Handling disconnections fundamentals guide](/x-api/fundamentals/handling-disconnections). ## Powerstream disconnection handling diff --git a/x-api/powerstream/operators.mdx b/x-api/powerstream/operators.mdx index bcf60af7f..aa33cfd4b 100644 --- a/x-api/powerstream/operators.mdx +++ b/x-api/powerstream/operators.mdx @@ -1,7 +1,6 @@ --- title: Powerstream Operators sidebarTitle: Operators -description: Complete list of operators for Powerstream filtering rules keywords: ["powerstream operators", "filter operators", "rule operators", "streaming operators", "powerstream rules", "operators guide"] --- diff --git a/x-api/powerstream/recovery-and-redundancy.mdx b/x-api/powerstream/recovery-and-redundancy.mdx index 3e2cdb4e3..58b8dc7ff 100644 --- a/x-api/powerstream/recovery-and-redundancy.mdx +++ b/x-api/powerstream/recovery-and-redundancy.mdx @@ -4,6 +4,7 @@ sidebarTitle: Recovery and redundancy keywords: ["powerstream recovery", "powerstream redundancy", "recovery features", "redundancy features", "fault tolerance", "error recovery"] --- + This page covers Powerstream-specific recovery and redundancy features. For comprehensive guidance on recovery and redundancy across all streaming endpoints, see the [Recovery and redundancy fundamentals guide](/x-api/fundamentals/recovery-and-redundancy). ## Powerstream recovery features diff --git a/x-api/spaces/get-space-by-id.mdx b/x-api/spaces/get-space-by-id.mdx index 6c70950fe..4374a22c1 100644 --- a/x-api/spaces/get-space-by-id.mdx +++ b/x-api/spaces/get-space-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/spaces/get-space-posts.mdx b/x-api/spaces/get-space-posts.mdx index 7efff44e6..e1fbd9acb 100644 --- a/x-api/spaces/get-space-posts.mdx +++ b/x-api/spaces/get-space-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/{id}/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/spaces/get-space-ticket-buyers.mdx b/x-api/spaces/get-space-ticket-buyers.mdx index 56e225303..fc500b9a7 100644 --- a/x-api/spaces/get-space-ticket-buyers.mdx +++ b/x-api/spaces/get-space-ticket-buyers.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/{id}/buyers ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/spaces/get-spaces-by-creator-ids.mdx b/x-api/spaces/get-spaces-by-creator-ids.mdx index dce7f72fe..10ce0c8e0 100644 --- a/x-api/spaces/get-spaces-by-creator-ids.mdx +++ b/x-api/spaces/get-spaces-by-creator-ids.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/by/creator_ids ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/spaces/get-spaces-by-ids.mdx b/x-api/spaces/get-spaces-by-ids.mdx index 309f3571a..89a151c81 100644 --- a/x-api/spaces/get-spaces-by-ids.mdx +++ b/x-api/spaces/get-spaces-by-ids.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/spaces/introduction.mdx b/x-api/spaces/introduction.mdx index 9b1dde449..a0563db45 100644 --- a/x-api/spaces/introduction.mdx +++ b/x-api/spaces/introduction.mdx @@ -2,6 +2,8 @@ title: Introduction sidebarTitle: Introduction keywords: ["spaces", "X spaces", "audio spaces", "live audio", "spaces API", "spaces lookup", "spaces search", "spaces discovery"] + +description: import { Button } from '/snippets/button.mdx'; The following page describes the Spaces endpoints included in the X API. To learn more about Spaces in genera... --- import { Button } from '/snippets/button.mdx'; diff --git a/x-api/spaces/search-spaces.mdx b/x-api/spaces/search-spaces.mdx index eb3ee21ea..a1289a7ed 100644 --- a/x-api/spaces/search-spaces.mdx +++ b/x-api/spaces/search-spaces.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/spaces/search ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/get-stream-rule-counts.mdx b/x-api/stream/get-stream-rule-counts.mdx index e4708bd99..f2e7dacf1 100644 --- a/x-api/stream/get-stream-rule-counts.mdx +++ b/x-api/stream/get-stream-rule-counts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/stream/rules/counts ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/get-stream-rules.mdx b/x-api/stream/get-stream-rules.mdx index 33f6bcc4f..3d22916c2 100644 --- a/x-api/stream/get-stream-rules.mdx +++ b/x-api/stream/get-stream-rules.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/stream/rules ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-10-sampled-posts.mdx b/x-api/stream/stream-10-sampled-posts.mdx index eb757f977..8caaf83ed 100644 --- a/x-api/stream/stream-10-sampled-posts.mdx +++ b/x-api/stream/stream-10-sampled-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/sample10/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-all-likes.mdx b/x-api/stream/stream-all-likes.mdx index 396ea3b1a..dcc95b92a 100644 --- a/x-api/stream/stream-all-likes.mdx +++ b/x-api/stream/stream-all-likes.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/likes/firehose/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-all-posts.mdx b/x-api/stream/stream-all-posts.mdx index 0176b635a..552fb99cf 100644 --- a/x-api/stream/stream-all-posts.mdx +++ b/x-api/stream/stream-all-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-english-posts.mdx b/x-api/stream/stream-english-posts.mdx index 05f99f6a2..e6a8b1bc9 100644 --- a/x-api/stream/stream-english-posts.mdx +++ b/x-api/stream/stream-english-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream/lang/en ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-filtered-posts.mdx b/x-api/stream/stream-filtered-posts.mdx index 67ae7d5fc..afa18701b 100644 --- a/x-api/stream/stream-filtered-posts.mdx +++ b/x-api/stream/stream-filtered-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-japanese-posts.mdx b/x-api/stream/stream-japanese-posts.mdx index 26113910b..f6e8fe9fc 100644 --- a/x-api/stream/stream-japanese-posts.mdx +++ b/x-api/stream/stream-japanese-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream/lang/ja ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-korean-posts.mdx b/x-api/stream/stream-korean-posts.mdx index 53b779919..32d4b1d37 100644 --- a/x-api/stream/stream-korean-posts.mdx +++ b/x-api/stream/stream-korean-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream/lang/ko ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-likes-compliance-data.mdx b/x-api/stream/stream-likes-compliance-data.mdx index ab366b9b1..852e9d14e 100644 --- a/x-api/stream/stream-likes-compliance-data.mdx +++ b/x-api/stream/stream-likes-compliance-data.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/likes/compliance/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-portuguese-posts.mdx b/x-api/stream/stream-portuguese-posts.mdx index f1da8cd4d..85e1e04c8 100644 --- a/x-api/stream/stream-portuguese-posts.mdx +++ b/x-api/stream/stream-portuguese-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/firehose/stream/lang/pt ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-post-labels.mdx b/x-api/stream/stream-post-labels.mdx index 48a78208d..e14e2566d 100644 --- a/x-api/stream/stream-post-labels.mdx +++ b/x-api/stream/stream-post-labels.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/label/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-posts-compliance-data.mdx b/x-api/stream/stream-posts-compliance-data.mdx index dc834d156..78a55261c 100644 --- a/x-api/stream/stream-posts-compliance-data.mdx +++ b/x-api/stream/stream-posts-compliance-data.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/compliance/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-sampled-likes.mdx b/x-api/stream/stream-sampled-likes.mdx index f073bb2b5..fd045533b 100644 --- a/x-api/stream/stream-sampled-likes.mdx +++ b/x-api/stream/stream-sampled-likes.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/likes/sample10/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-sampled-posts.mdx b/x-api/stream/stream-sampled-posts.mdx index 140cea99c..1bace5451 100644 --- a/x-api/stream/stream-sampled-posts.mdx +++ b/x-api/stream/stream-sampled-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/sample/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/stream-users-compliance-data.mdx b/x-api/stream/stream-users-compliance-data.mdx index a78937542..89f03329a 100644 --- a/x-api/stream/stream-users-compliance-data.mdx +++ b/x-api/stream/stream-users-compliance-data.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/compliance/stream ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/stream/update-stream-rules.mdx b/x-api/stream/update-stream-rules.mdx index e69e135c1..daf478ebc 100644 --- a/x-api/stream/update-stream-rules.mdx +++ b/x-api/stream/update-stream-rules.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/tweets/search/stream/rules ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/trends/get-ai-trends-by-id.mdx b/x-api/trends/get-ai-trends-by-id.mdx index aa8d55508..9c8de6c2d 100644 --- a/x-api/trends/get-ai-trends-by-id.mdx +++ b/x-api/trends/get-ai-trends-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/ai_trends/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/trends/get-personalized-trends.mdx b/x-api/trends/get-personalized-trends.mdx index b2b7aecf0..fdb61263b 100644 --- a/x-api/trends/get-personalized-trends.mdx +++ b/x-api/trends/get-personalized-trends.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/personalized_trends ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/trends/get-trends-by-woeid.mdx b/x-api/trends/get-trends-by-woeid.mdx index c591cdff5..349a005a6 100644 --- a/x-api/trends/get-trends-by-woeid.mdx +++ b/x-api/trends/get-trends-by-woeid.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/trends/by/woeid/{woeid} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/usage/get-usage.mdx b/x-api/usage/get-usage.mdx index fe624116f..ac3cc6c3c 100644 --- a/x-api/usage/get-usage.mdx +++ b/x-api/usage/get-usage.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/usage/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/block-dms.mdx b/x-api/users/block-dms.mdx index 6b9e9b883..7212e4e36 100644 --- a/x-api/users/block-dms.mdx +++ b/x-api/users/block-dms.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/dm/block ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/blocks/integrate.mdx b/x-api/users/blocks/integrate.mdx index 1c534e606..a670874f5 100644 --- a/x-api/users/blocks/integrate.mdx +++ b/x-api/users/blocks/integrate.mdx @@ -1,7 +1,6 @@ --- title: Integration Guide sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating blocks endpoints keywords: ["blocks integration", "block users integration", "blocks guide"] --- diff --git a/x-api/users/blocks/migrate.mdx b/x-api/users/blocks/migrate.mdx index 334f8b1f4..40a4ea67a 100644 --- a/x-api/users/blocks/migrate.mdx +++ b/x-api/users/blocks/migrate.mdx @@ -4,6 +4,7 @@ sidebarTitle: Migration guide keywords: ["blocks migration", "blocks migrate", "v1.1 to v2 blocks", "blocks migration guide", "migrate blocks"] --- + import { Button } from '/snippets/button.mdx'; diff --git a/x-api/users/create-bookmark.mdx b/x-api/users/create-bookmark.mdx index 7474d20cd..62cbefe9a 100644 --- a/x-api/users/create-bookmark.mdx +++ b/x-api/users/create-bookmark.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/bookmarks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/delete-bookmark.mdx b/x-api/users/delete-bookmark.mdx index 78d0e4078..22457d0af 100644 --- a/x-api/users/delete-bookmark.mdx +++ b/x-api/users/delete-bookmark.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/bookmarks/{tweet_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/follow-list.mdx b/x-api/users/follow-list.mdx index e1220a1f9..2ddb6775e 100644 --- a/x-api/users/follow-list.mdx +++ b/x-api/users/follow-list.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/followed_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/follow-user.mdx b/x-api/users/follow-user.mdx index 449d74830..6bd98c729 100644 --- a/x-api/users/follow-user.mdx +++ b/x-api/users/follow-user.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/following ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/follows/migrate/overview.mdx b/x-api/users/follows/migrate/overview.mdx index d53a8e53c..30cdb607a 100644 --- a/x-api/users/follows/migrate/overview.mdx +++ b/x-api/users/follows/migrate/overview.mdx @@ -1,73 +1,73 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["follows migration", "follows migrate", "v1.1 to v2 follows", "follows migration guide", "migrate follows"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing X API’s follows endpoints - -### Follows lookup - -The v2 follows lookup endpoints will replace the standard v1.1 [followers/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids), v1.1 [followers/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-followers-list), v1.1 [friends/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friends-ids), and v1.1 [friends/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friends-list) endpoints. - -The following tables compare the various types of follows lookup endpoints: - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| HTTP methods supported | `GET` | `GET` | -| Host domain | `https://api.x.com` | `https://api.x.com` | -| Endpoint path | /1.1/friends/ids.json

/1.1/friends/list.json

/1.1/followers/ids.json

/1.1/followers/list.json | /2/users/:id/following

/2/users/:id/followers | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 15 requests per 15 min (per user)

15 requests per 15 min (per app) | 15 requests per 15 min (per user)

15 requests per 15 min (per app) | -| Maximum users per response | GET friends/id & GET followers/id return a maximum of 5000 users IDs per page.



GET friends/list & GET followers/list return a maximum of 200 user objects per page. | 1000 user objects per page | -| Pagination | Token returns in a next_cursor field, which can then be passed as the value to the cursor parameter to return the next page of results. | Token returns in a next_token field, which can then be passed as the value to the token parameter to return the next page of results.

The v2 payload also delivers a previous_token field, which can also be passed with the pagination_token parameter to return the previous page of results. | -| JSON format | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | -| Supports selecting which [fields](/x-api/fundamentals/data-dictionary) return in the payload | | ✔ | -| Supports the Post [annotations](/x-api/fundamentals/post-annotations) fields | | ✔ | -| Supports requesting new [metrics](/x-api/fundamentals/metrics) fields | | ✔ | -| Supports the [conversation_id](/x-api/fundamentals/conversation-id) field | | ✔ | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [project](/resources/fundamentals/developer-apps) | | ✔ | - -#### Manage follows - -The v2 manage follows endpoints will replace the standard v1.1 [POST friendships/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create) and [POST friendships/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy) endpoints. - -The following tables compare the standard v1.1 and X API v2 create follow endpoints: - -#### Follow a user - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | POST | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/friendships/create.json | /2/users/:id/following | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 50 requests per 15 min | 50 requests per 15 min | -| Maximum daily operations per users | 400 | 400 | -| Maximum daily operations per app | 1000 | 1000 | -| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | - -#### Unfollow a user - -The following tables compare the standard v1.1 and X API v2 delete follow endpoints: - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | DELETE | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/friendships/destroy.json | /2/users/:source\_user\_id/following/:target\_user\_id | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 15 requests per 15 min (per user) | 50 requests per 15 min (per user) | -| Maximum daily operations per app | None | 500 | -| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | - -**Other migration resources** - -[Follows lookup: Standard v1.1 to X API v2](/x-api/users/follows/migrate/standard-to-twitter-api-v2) - -[Manage follows: Standard v1.1 to X API v2](/x-api/users/follows#manage-follows-standard-v1-1-compared-to-x-api-v2) - +--- +title: Overview +sidebarTitle: Overview +keywords: ["follows migration", "follows migrate", "v1.1 to v2 follows", "follows migration guide", "migrate follows"] + + +import { Button } from '/snippets/button.mdx'; + +## Comparing X API’s follows endpoints + +### Follows lookup + +The v2 follows lookup endpoints will replace the standard v1.1 [followers/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids), v1.1 [followers/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-followers-list), v1.1 [friends/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friends-ids), and v1.1 [friends/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friends-list) endpoints. + +The following tables compare the various types of follows lookup endpoints: + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| HTTP methods supported | `GET` | `GET` | +| Host domain | `https://api.x.com` | `https://api.x.com` | +| Endpoint path | /1.1/friends/ids.json

/1.1/friends/list.json

/1.1/followers/ids.json

/1.1/followers/list.json | /2/users/:id/following

/2/users/:id/followers | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context

App only | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE

App only | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 15 requests per 15 min (per user)

15 requests per 15 min (per app) | 15 requests per 15 min (per user)

15 requests per 15 min (per app) | +| Maximum users per response | GET friends/id & GET followers/id return a maximum of 5000 users IDs per page.



GET friends/list & GET followers/list return a maximum of 200 user objects per page. | 1000 user objects per page | +| Pagination | Token returns in a next_cursor field, which can then be passed as the value to the cursor parameter to return the next page of results. | Token returns in a next_token field, which can then be passed as the value to the token parameter to return the next page of results.

The v2 payload also delivers a previous_token field, which can also be passed with the pagination_token parameter to return the previous page of results. | +| JSON format | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | +| Supports selecting which [fields](/x-api/fundamentals/data-dictionary) return in the payload | | ✔ | +| Supports the Post [annotations](/x-api/fundamentals/post-annotations) fields | | ✔ | +| Supports requesting new [metrics](/x-api/fundamentals/metrics) fields | | ✔ | +| Supports the [conversation_id](/x-api/fundamentals/conversation-id) field | | ✔ | +| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [project](/resources/fundamentals/developer-apps) | | ✔ | + +#### Manage follows + +The v2 manage follows endpoints will replace the standard v1.1 [POST friendships/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create) and [POST friendships/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy) endpoints. + +The following tables compare the standard v1.1 and X API v2 create follow endpoints: + +#### Follow a user + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | POST | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/friendships/create.json | /2/users/:id/following | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 50 requests per 15 min | 50 requests per 15 min | +| Maximum daily operations per users | 400 | 400 | +| Maximum daily operations per app | 1000 | 1000 | +| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | + +#### Unfollow a user + +The following tables compare the standard v1.1 and X API v2 delete follow endpoints: + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | DELETE | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/friendships/destroy.json | /2/users/:source\_user\_id/following/:target\_user\_id | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 15 requests per 15 min (per user) | 50 requests per 15 min (per user) | +| Maximum daily operations per app | None | 500 | +| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | + +**Other migration resources** + +[Follows lookup: Standard v1.1 to X API v2](/x-api/users/follows/migrate/standard-to-twitter-api-v2) + +[Manage follows: Standard v1.1 to X API v2](/x-api/users/follows#manage-follows-standard-v1-1-compared-to-x-api-v2) + [X API migration hub](/x-api/migrate/overview) \ No newline at end of file diff --git a/x-api/users/follows/migrate/standard-to-twitter-api-v2.mdx b/x-api/users/follows/migrate/standard-to-twitter-api-v2.mdx index e0bb58be5..a599856ef 100644 --- a/x-api/users/follows/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/users/follows/migrate/standard-to-twitter-api-v2.mdx @@ -1,197 +1,47 @@ ---- -title: v1 to v2 -sidebarTitle: v1 to v2 -keywords: ["v1.1 to v2 migration", "follows migration", "migrate follows", "standard to v2 follows", "v1 to v2 follows", "migration guide"] ---- - -import { Button } from '/snippets/button.mdx'; - -#### Manage follows: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST friendships/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create) and [POST friendships/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 manage follows endpoints. - -* **Similarities** - * OAuth 1.0a User Context -* **Differences** - * Endpoint URLs - * App and Project requirements - * HTTP methods - * Request parameters - - - -#### Similarities - -**OAuth 1.0a User Context authentication method** - -Both the endpoint versions support [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 manage follows endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/friendships/create.json - (follow a user) - * POST https://api.x.com/1.1/friendships/destroy.json - (unfollow a user) -* X API v2 endpoint: - * POST https://api.x.com/2/users/:id/following - (follow a user) - * DELETE https://api.x.com/2/users/:source\_user\_id/following/:target\_user\_id - (unfollow a user) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard v1.1 | X API v2 | -| :--- | :--- | -| No equivalent | id (POST), source\_user\_id (DELETE) | -| user_id | target\_user\_id | -| screen_name | No equivalent | - -Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters (for the POST endpoint) or path parameters (for the DELETE endpoint). - -Also, the v2 id and source\_user\_id are not required when using the standard v1.1 endpoints since the Access Tokens passed with OAuth 1.0a User Context inferred which user was initiating the follow/unfollow. - ---- - -## Code examples - -### Follow a user (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123456789/following" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"target_user_id": "2244994945"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/following" -response = requests.post(url, auth=auth, json={"target_user_id": "2244994945"}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Follow a user -response = client.users.follow( - source_user_id="123456789", - target_user_id="2244994945" -) -print(f"Following: {response.data.following}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Follow a user -const response = await client.users.follow("123456789", { - targetUserId: "2244994945", -}); -console.log(`Following: ${response.data?.following}`); -``` - - - -### Unfollow a user (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/users/123456789/following/2244994945" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/following/2244994945" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Unfollow a user -response = client.users.unfollow( - source_user_id="123456789", - target_user_id="2244994945" -) -print(f"Following: {response.data.following}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Unfollow a user -const response = await client.users.unfollow("123456789", "2244994945"); -console.log(`Following: ${response.data?.following}`); -``` - - +--- +title: v1 to v2 +sidebarTitle: v1 to v2 +keywords: ["v1.1 to v2 migration", "follows migration", "migrate follows", "standard to v2 follows", "v1 to v2 follows", "migration guide"] + + +--- +import { Button } from '/snippets/button.mdx'; + +#### Manage follows: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST friendships/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create) and [POST friendships/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 manage follows endpoints. + +* **Similarities** + * OAuth 1.0a User Context +* **Differences** + * Endpoint URLs + * App and Project requirements + * HTTP methods + * Request parameters + + + +#### Similarities + +**OAuth 1.0a User Context authentication method** + +Both the endpoint versions support [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 manage follows endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/friendships/create.json + (follow a user) + * POST https://api.x.com/1.1/friendships/destroy.json + (unfollow a user) +* X API v2 endpoint: + * POST https://api.x.com/2/users/:id/following + (follow a user) + * DELETE https://api.x.com/2/users/:source\_user\_id/following/:target\_user\_id + (unfollow a user) + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundam \ No newline at end of file diff --git a/x-api/users/get-affiliates.mdx b/x-api/users/get-affiliates.mdx index de66976f2..17ab21cb0 100644 --- a/x-api/users/get-affiliates.mdx +++ b/x-api/users/get-affiliates.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/affiliates ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-blocking.mdx b/x-api/users/get-blocking.mdx index 8ca0ad36f..090c530b6 100644 --- a/x-api/users/get-blocking.mdx +++ b/x-api/users/get-blocking.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/blocking ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-bookmark-folders.mdx b/x-api/users/get-bookmark-folders.mdx index dfdfbee9c..f58360b6f 100644 --- a/x-api/users/get-bookmark-folders.mdx +++ b/x-api/users/get-bookmark-folders.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks/folders ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-bookmarks-by-folder-id.mdx b/x-api/users/get-bookmarks-by-folder-id.mdx index 98c7e3b07..6f0d421f4 100644 --- a/x-api/users/get-bookmarks-by-folder-id.mdx +++ b/x-api/users/get-bookmarks-by-folder-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks/folders/{folder_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-bookmarks.mdx b/x-api/users/get-bookmarks.mdx index fc3894243..e1367873c 100644 --- a/x-api/users/get-bookmarks.mdx +++ b/x-api/users/get-bookmarks.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/bookmarks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-followed-lists.mdx b/x-api/users/get-followed-lists.mdx index 98d9c4a4c..f0f5b1065 100644 --- a/x-api/users/get-followed-lists.mdx +++ b/x-api/users/get-followed-lists.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/followed_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-followers.mdx b/x-api/users/get-followers.mdx index adb2d22c6..99e4e6a7c 100644 --- a/x-api/users/get-followers.mdx +++ b/x-api/users/get-followers.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/followers ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-following.mdx b/x-api/users/get-following.mdx index 2995b7ad4..1f51f23b1 100644 --- a/x-api/users/get-following.mdx +++ b/x-api/users/get-following.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/following ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-liked-posts.mdx b/x-api/users/get-liked-posts.mdx index a56f559e3..7a4f973d8 100644 --- a/x-api/users/get-liked-posts.mdx +++ b/x-api/users/get-liked-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/liked_tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-list-memberships.mdx b/x-api/users/get-list-memberships.mdx index 1935f6b5d..4c8272dc1 100644 --- a/x-api/users/get-list-memberships.mdx +++ b/x-api/users/get-list-memberships.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/list_memberships ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-mentions.mdx b/x-api/users/get-mentions.mdx index 4d089897d..7b2833a73 100644 --- a/x-api/users/get-mentions.mdx +++ b/x-api/users/get-mentions.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/mentions ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-muting.mdx b/x-api/users/get-muting.mdx index dbe6684e6..ef9b9babd 100644 --- a/x-api/users/get-muting.mdx +++ b/x-api/users/get-muting.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/muting ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-my-user.mdx b/x-api/users/get-my-user.mdx index bad7698d8..e8dccb741 100644 --- a/x-api/users/get-my-user.mdx +++ b/x-api/users/get-my-user.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/me ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-owned-lists.mdx b/x-api/users/get-owned-lists.mdx index b3f4c7517..81d220f86 100644 --- a/x-api/users/get-owned-lists.mdx +++ b/x-api/users/get-owned-lists.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/owned_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-pinned-lists.mdx b/x-api/users/get-pinned-lists.mdx index 1d70e9542..680c1fd97 100644 --- a/x-api/users/get-pinned-lists.mdx +++ b/x-api/users/get-pinned-lists.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/pinned_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-posts.mdx b/x-api/users/get-posts.mdx index 7b9b6cfd5..708a5fd42 100644 --- a/x-api/users/get-posts.mdx +++ b/x-api/users/get-posts.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/tweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-public-keys-for-multiple-users.mdx b/x-api/users/get-public-keys-for-multiple-users.mdx index 0835ad99c..6dc69d250 100644 --- a/x-api/users/get-public-keys-for-multiple-users.mdx +++ b/x-api/users/get-public-keys-for-multiple-users.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/public_keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-reposts-of-me.mdx b/x-api/users/get-reposts-of-me.mdx index 7a00370b5..3915f215d 100644 --- a/x-api/users/get-reposts-of-me.mdx +++ b/x-api/users/get-reposts-of-me.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/reposts_of_me ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-timeline.mdx b/x-api/users/get-timeline.mdx index 1705bcb91..42791925a 100644 --- a/x-api/users/get-timeline.mdx +++ b/x-api/users/get-timeline.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/timelines/reverse_chronological ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-user-by-id.mdx b/x-api/users/get-user-by-id.mdx index 6ff1b1306..d6eba0f4b 100644 --- a/x-api/users/get-user-by-id.mdx +++ b/x-api/users/get-user-by-id.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-user-by-username.mdx b/x-api/users/get-user-by-username.mdx index bcd665927..fc7b48dce 100644 --- a/x-api/users/get-user-by-username.mdx +++ b/x-api/users/get-user-by-username.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/by/username/{username} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-user-public-keys.mdx b/x-api/users/get-user-public-keys.mdx index 804e1cbc7..b20716f9a 100644 --- a/x-api/users/get-user-public-keys.mdx +++ b/x-api/users/get-user-public-keys.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/{id}/public_keys ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-users-by-ids.mdx b/x-api/users/get-users-by-ids.mdx index cbbbf5ce0..9532932b2 100644 --- a/x-api/users/get-users-by-ids.mdx +++ b/x-api/users/get-users-by-ids.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/get-users-by-usernames.mdx b/x-api/users/get-users-by-usernames.mdx index 13887ad74..2eb597ad1 100644 --- a/x-api/users/get-users-by-usernames.mdx +++ b/x-api/users/get-users-by-usernames.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/by ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/like-post.mdx b/x-api/users/like-post.mdx index e6197dc22..004cac235 100644 --- a/x-api/users/like-post.mdx +++ b/x-api/users/like-post.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/likes ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/lookup/integrate.mdx b/x-api/users/lookup/integrate.mdx index 25427fd3d..b62378814 100644 --- a/x-api/users/lookup/integrate.mdx +++ b/x-api/users/lookup/integrate.mdx @@ -1,369 +1,368 @@ ---- -title: Integration Guide -sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating User lookup -keywords: ["user lookup integration", "users integration guide", "user lookup implementation"] ---- - -import { Button } from '/snippets/button.mdx'; - -This guide covers the key concepts you need to integrate the User lookup endpoints into your application. - ---- - -## Authentication - -All X API v2 endpoints require authentication. Choose the method that fits your use case: - -| Method | Best for | Can access private metrics? | -|:-------|:---------|:---------------------------| -| [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) | Server-to-server, public data | No | -| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | User-facing apps | Yes (for authorized user's data) | -| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy integrations | Yes (for authorized user's data) | - -### App-Only authentication - -For public user data, use a Bearer Token: - - - -```bash cURL -curl "https://api.x.com/2/users/by/username/XDevelopers" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user by username -response = client.users.get_by_username("XDevelopers") -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -const response = await client.users.getByUsername("XDevelopers"); -console.log(response.data); -``` - - - -### User Context authentication - -Required for the authenticated user endpoint (`/2/users/me`): - - - -```bash cURL -curl "https://api.x.com/2/users/me" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" -``` - -```python Python SDK -from xdk import Client - -# Using OAuth 2.0 user access token -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Get authenticated user's profile -response = client.users.get_me() -print(response.data) -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -// Using OAuth 2.0 user access token -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -const response = await client.users.getMe(); -console.log(response.data); -``` - - - - -The `/2/users/me` endpoint only works with User Context authentication. App-Only tokens will return an error. - - ---- - -## Fields and expansions - -The X API v2 returns minimal data by default. Use `fields` and `expansions` to request exactly what you need. - -### Default response - -```json -{ - "data": { - "id": "2244994945", - "name": "X Developers", - "username": "XDevelopers" - } -} -``` - -### Available fields - - -| Field | Description | -|:------|:------------| -| `created_at` | Account creation timestamp | -| `description` | User bio | -| `entities` | Parsed URLs in bio | -| `location` | User-defined location | -| `pinned_tweet_id` | Pinned Post ID | -| `profile_image_url` | Avatar URL | -| `protected` | Whether account is protected | -| `public_metrics` | Follower/following counts | -| `url` | Website URL | -| `verified` | Verification status | -| `withheld` | Withholding information | - - - -| Field | Description | -|:------|:------------| -| `created_at` | Post creation timestamp | -| `text` | Post content | -| `public_metrics` | Engagement counts | -| `entities` | Hashtags, mentions, URLs | - - -### Example with fields - - - -```bash cURL -curl "https://api.x.com/2/users/by/username/XDevelopers?\ -user.fields=created_at,description,public_metrics,verified&\ -expansions=pinned_tweet_id&\ -tweet.fields=created_at,public_metrics" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user with additional fields and expansions -response = client.users.get_by_username( - "XDevelopers", - user_fields=["created_at", "description", "public_metrics", "verified"], - expansions=["pinned_tweet_id"], - tweet_fields=["created_at", "public_metrics"] -) - -print(response.data) -print(response.includes) # Contains expanded pinned tweet -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -const response = await client.users.getByUsername("XDevelopers", { - userFields: ["created_at", "description", "public_metrics", "verified"], - expansions: ["pinned_tweet_id"], - tweetFields: ["created_at", "public_metrics"], -}); - -console.log(response.data); -console.log(response.includes); // Contains expanded pinned tweet -``` - - - -### Response with expansions - -```json -{ - "data": { - "id": "2244994945", - "name": "X Developers", - "username": "XDevelopers", - "created_at": "2013-12-14T04:35:55.000Z", - "verified": true, - "pinned_tweet_id": "1234567890", - "public_metrics": { - "followers_count": 583423, - "following_count": 2048, - "tweet_count": 14052 - } - }, - "includes": { - "tweets": [ - { - "id": "1234567890", - "text": "Welcome to the X Developer Platform!", - "created_at": "2024-01-15T10:00:00.000Z" - } - ] - } -} -``` - - - Learn more about customizing responses - - ---- - -## Batch lookups - -Look up multiple users in a single request: - - - -```bash cURL (by IDs) -curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\ -user.fields=username,verified" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```bash cURL (by usernames) -curl "https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&\ -user.fields=username,verified" \ - -H "Authorization: Bearer $BEARER_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get multiple users by IDs -response = client.users.get_users( - ids=["2244994945", "783214", "6253282"], - user_fields=["username", "verified"] -) -for user in response.data: - print(f"{user.username}: {user.verified}") - -# Get multiple users by usernames -response = client.users.get_users_by_usernames( - usernames=["XDevelopers", "X", "XAPI"], - user_fields=["username", "verified"] -) -for user in response.data: - print(f"{user.username}: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -// Get multiple users by IDs -const byIds = await client.users.getUsers({ - ids: ["2244994945", "783214", "6253282"], - userFields: ["username", "verified"], -}); -byIds.data.forEach((user) => { - console.log(`${user.username}: ${user.verified}`); -}); - -// Get multiple users by usernames -const byUsernames = await client.users.getUsersByUsernames({ - usernames: ["XDevelopers", "X", "XAPI"], - userFields: ["username", "verified"], -}); -byUsernames.data.forEach((user) => { - console.log(`${user.username}: ${user.verified}`); -}); -``` - - - - -Batch requests are limited to 100 users. Use multiple requests for larger datasets. - - ---- - -## Error handling - -### Common errors - -| Status | Error | Solution | -|:-------|:------|:---------| -| 400 | Invalid request | Check parameter formatting | -| 401 | Unauthorized | Verify authentication credentials | -| 403 | Forbidden | Check App permissions | -| 404 | Not Found | User doesn't exist or was suspended | -| 429 | Too Many Requests | Wait and retry (see rate limits) | - -### Suspended or deleted users - -If a user is suspended or deleted: -- Single user lookup returns `404` -- Multi-user lookup omits the user from results with an `errors` array - -```json -{ - "data": [ - { "id": "2244994945", "username": "XDevelopers" } - ], - "errors": [ - { - "resource_id": "1234567890", - "resource_type": "user", - "title": "Not Found Error", - "detail": "Could not find user with id: [1234567890]." - } - ] -} -``` - -### Protected users - -For protected accounts you don't follow: -- Basic info (id, name, username) is available -- Protected content (pinned Post) may be restricted -- `protected: true` indicates the account status - ---- - -## Best practices - - - - Use multi-user endpoints to fetch up to 100 users at once, reducing API calls. - - - Specify only the fields you need to minimize response size. - - - Cache user profiles locally to reduce repeated requests. - - - Check for partial errors in batch responses. - - - ---- - -## Next steps - - - - Complete endpoint documentation - - - All available objects and fields - - - Working code examples - - - Handle errors gracefully - - +--- +title: Integration Guide +sidebarTitle: Integration Guide +keywords: ["user lookup integration", "users integration guide", "user lookup implementation"] +--- + +import { Button } from '/snippets/button.mdx'; + +This guide covers the key concepts you need to integrate the User lookup endpoints into your application. + +--- + +## Authentication + +All X API v2 endpoints require authentication. Choose the method that fits your use case: + +| Method | Best for | Can access private metrics? | +|:-------|:---------|:---------------------------| +| [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) | Server-to-server, public data | No | +| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | User-facing apps | Yes (for authorized user's data) | +| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy integrations | Yes (for authorized user's data) | + +### App-Only authentication + +For public user data, use a Bearer Token: + + + +```bash cURL +curl "https://api.x.com/2/users/by/username/XDevelopers" \ + -H "Authorization: Bearer $BEARER_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_BEARER_TOKEN") + +# Get user by username +response = client.users.get_by_username("XDevelopers") +print(response.data) +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); + +const response = await client.users.getByUsername("XDevelopers"); +console.log(response.data); +``` + + + +### User Context authentication + +Required for the authenticated user endpoint (`/2/users/me`): + + + +```bash cURL +curl "https://api.x.com/2/users/me" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" +``` + +```python Python SDK +from xdk import Client + +# Using OAuth 2.0 user access token +client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") + +# Get authenticated user's profile +response = client.users.get_me() +print(response.data) +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +// Using OAuth 2.0 user access token +const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); + +const response = await client.users.getMe(); +console.log(response.data); +``` + + + + +The `/2/users/me` endpoint only works with User Context authentication. App-Only tokens will return an error. + + +--- + +## Fields and expansions + +The X API v2 returns minimal data by default. Use `fields` and `expansions` to request exactly what you need. + +### Default response + +```json +{ + "data": { + "id": "2244994945", + "name": "X Developers", + "username": "XDevelopers" + } +} +``` + +### Available fields + + +| Field | Description | +|:------|:------------| +| `created_at` | Account creation timestamp | +| `description` | User bio | +| `entities` | Parsed URLs in bio | +| `location` | User-defined location | +| `pinned_tweet_id` | Pinned Post ID | +| `profile_image_url` | Avatar URL | +| `protected` | Whether account is protected | +| `public_metrics` | Follower/following counts | +| `url` | Website URL | +| `verified` | Verification status | +| `withheld` | Withholding information | + + + +| Field | Description | +|:------|:------------| +| `created_at` | Post creation timestamp | +| `text` | Post content | +| `public_metrics` | Engagement counts | +| `entities` | Hashtags, mentions, URLs | + + +### Example with fields + + + +```bash cURL +curl "https://api.x.com/2/users/by/username/XDevelopers?\ +user.fields=created_at,description,public_metrics,verified&\ +expansions=pinned_tweet_id&\ +tweet.fields=created_at,public_metrics" \ + -H "Authorization: Bearer $BEARER_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_BEARER_TOKEN") + +# Get user with additional fields and expansions +response = client.users.get_by_username( + "XDevelopers", + user_fields=["created_at", "description", "public_metrics", "verified"], + expansions=["pinned_tweet_id"], + tweet_fields=["created_at", "public_metrics"] +) + +print(response.data) +print(response.includes) # Contains expanded pinned tweet +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); + +const response = await client.users.getByUsername("XDevelopers", { + userFields: ["created_at", "description", "public_metrics", "verified"], + expansions: ["pinned_tweet_id"], + tweetFields: ["created_at", "public_metrics"], +}); + +console.log(response.data); +console.log(response.includes); // Contains expanded pinned tweet +``` + + + +### Response with expansions + +```json +{ + "data": { + "id": "2244994945", + "name": "X Developers", + "username": "XDevelopers", + "created_at": "2013-12-14T04:35:55.000Z", + "verified": true, + "pinned_tweet_id": "1234567890", + "public_metrics": { + "followers_count": 583423, + "following_count": 2048, + "tweet_count": 14052 + } + }, + "includes": { + "tweets": [ + { + "id": "1234567890", + "text": "Welcome to the X Developer Platform!", + "created_at": "2024-01-15T10:00:00.000Z" + } + ] + } +} +``` + + + Learn more about customizing responses + + +--- + +## Batch lookups + +Look up multiple users in a single request: + + + +```bash cURL (by IDs) +curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\ +user.fields=username,verified" \ + -H "Authorization: Bearer $BEARER_TOKEN" +``` + +```bash cURL (by usernames) +curl "https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&\ +user.fields=username,verified" \ + -H "Authorization: Bearer $BEARER_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_BEARER_TOKEN") + +# Get multiple users by IDs +response = client.users.get_users( + ids=["2244994945", "783214", "6253282"], + user_fields=["username", "verified"] +) +for user in response.data: + print(f"{user.username}: {user.verified}") + +# Get multiple users by usernames +response = client.users.get_users_by_usernames( + usernames=["XDevelopers", "X", "XAPI"], + user_fields=["username", "verified"] +) +for user in response.data: + print(f"{user.username}: {user.verified}") +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); + +// Get multiple users by IDs +const byIds = await client.users.getUsers({ + ids: ["2244994945", "783214", "6253282"], + userFields: ["username", "verified"], +}); +byIds.data.forEach((user) => { + console.log(`${user.username}: ${user.verified}`); +}); + +// Get multiple users by usernames +const byUsernames = await client.users.getUsersByUsernames({ + usernames: ["XDevelopers", "X", "XAPI"], + userFields: ["username", "verified"], +}); +byUsernames.data.forEach((user) => { + console.log(`${user.username}: ${user.verified}`); +}); +``` + + + + +Batch requests are limited to 100 users. Use multiple requests for larger datasets. + + +--- + +## Error handling + +### Common errors + +| Status | Error | Solution | +|:-------|:------|:---------| +| 400 | Invalid request | Check parameter formatting | +| 401 | Unauthorized | Verify authentication credentials | +| 403 | Forbidden | Check App permissions | +| 404 | Not Found | User doesn't exist or was suspended | +| 429 | Too Many Requests | Wait and retry (see rate limits) | + +### Suspended or deleted users + +If a user is suspended or deleted: +- Single user lookup returns `404` +- Multi-user lookup omits the user from results with an `errors` array + +```json +{ + "data": [ + { "id": "2244994945", "username": "XDevelopers" } + ], + "errors": [ + { + "resource_id": "1234567890", + "resource_type": "user", + "title": "Not Found Error", + "detail": "Could not find user with id: [1234567890]." + } + ] +} +``` + +### Protected users + +For protected accounts you don't follow: +- Basic info (id, name, username) is available +- Protected content (pinned Post) may be restricted +- `protected: true` indicates the account status + +--- + +## Best practices + + + + Use multi-user endpoints to fetch up to 100 users at once, reducing API calls. + + + Specify only the fields you need to minimize response size. + + + Cache user profiles locally to reduce repeated requests. + + + Check for partial errors in batch responses. + + + +--- + +## Next steps + + + + Complete endpoint documentation + + + All available objects and fields + + + Working code examples + + + Handle errors gracefully + + diff --git a/x-api/users/lookup/migrate/overview.mdx b/x-api/users/lookup/migrate/overview.mdx index 7a5bcb4e1..45aa75c05 100644 --- a/x-api/users/lookup/migrate/overview.mdx +++ b/x-api/users/lookup/migrate/overview.mdx @@ -1,39 +1,39 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["user lookup migration", "users lookup migration", "v1.1 to v2 user lookup", "user lookup migration guide", "migrate user lookup"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing X API’s users lookup endpoints - -The v2 user lookup endpoints will replace the standard v1.1 [GET users/lookup](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup.html) and [GET users/show](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-show.html) endpoints. If you have code, apps, or tools that use one of these versions of the user lookup endpoints, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you.  -  - -The following tables compare the various types of users lookup endpoints: -  - -| | | | -| :--- | :--- | :--- | -| **Description** | **Standard v1.1** | **X API v2** | -| HTTP methods supported | `GET` | `GET` | -| Host domain | `https://api.x.com` | `https://api.x.com` | -| Endpoint path | `/1.1/users/show.json` `/1.1/users/lookup.json` | `/2/users`

`/2/users/:id`

`/2/users/by`

`/2/users/by/:username` | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

App only

OAuth 2.0 Authorization Code with PKCE | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 900 requests per 15 min (per user)

/show - 900 requests per 15 min (per app)
/lookup - 300 requests per 15 min (per app) | 900 requests per 15 min (per user)

300 requests per 15 min (per app) | -| Maximum Users per response | /show -  1

/lookup - 100 | 100 | -| JSON response object format | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | -| Supports selecting which [fields](/x-api/fundamentals/data-dictionary) return in the payload | | ✔ | -| Supports the [annotations](/x-api/fundamentals/post-annotations) fields (on pinned Post) | | ✔ | -| Supports requesting new [metrics](/x-api/fundamentals/metrics) fields (on pinned Post) | | ✔ | -| Supports the [conversation_id](/x-api/fundamentals/conversation-id) field (on pinned Post) | | ✔ | -| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [project](/resources/fundamentals/developer-apps) | | ✔ | - -**Other migration resources** - -[User lookup: Standard v1.1 to X API v2](/x-api/users/lookup/migrate/standard-to-twitter-api-v2) - -[X API migration hub](/x-api/migrate/overview) - -[Check out some sample code for these endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code "Check out some sample code for these endpoints") +--- +title: Overview +sidebarTitle: Overview +keywords: ["user lookup migration", "users lookup migration", "v1.1 to v2 user lookup", "user lookup migration guide", "migrate user lookup"] + + +import { Button } from '/snippets/button.mdx'; + +## Comparing X API’s users lookup endpoints + +The v2 user lookup endpoints will replace the standard v1.1 [GET users/lookup](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup.html) and [GET users/show](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-show.html) endpoints. If you have code, apps, or tools that use one of these versions of the user lookup endpoints, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you.  +  + +The following tables compare the various types of users lookup endpoints: +  + +| | | | +| :--- | :--- | :--- | +| **Description** | **Standard v1.1** | **X API v2** | +| HTTP methods supported | `GET` | `GET` | +| Host domain | `https://api.x.com` | `https://api.x.com` | +| Endpoint path | `/1.1/users/show.json` `/1.1/users/lookup.json` | `/2/users`

`/2/users/:id`

`/2/users/by`

`/2/users/by/:username` | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

App only

OAuth 2.0 Authorization Code with PKCE | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 900 requests per 15 min (per user)

/show - 900 requests per 15 min (per app)
/lookup - 300 requests per 15 min (per app) | 900 requests per 15 min (per user)

300 requests per 15 min (per app) | +| Maximum Users per response | /show -  1

/lookup - 100 | 100 | +| JSON response object format | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | +| Supports selecting which [fields](/x-api/fundamentals/data-dictionary) return in the payload | | ✔ | +| Supports the [annotations](/x-api/fundamentals/post-annotations) fields (on pinned Post) | | ✔ | +| Supports requesting new [metrics](/x-api/fundamentals/metrics) fields (on pinned Post) | | ✔ | +| Supports the [conversation_id](/x-api/fundamentals/conversation-id) field (on pinned Post) | | ✔ | +| Requires the use of credentials from a [developer App](/resources/fundamentals/developer-apps) associated with a [project](/resources/fundamentals/developer-apps) | | ✔ | + +**Other migration resources** + +[User lookup: Standard v1.1 to X API v2](/x-api/users/lookup/migrate/standard-to-twitter-api-v2) + +[X API migration hub](/x-api/migrate/overview) + +[Check out some sample code for these endpoints](https://github.com/xdevplatform/Twitter-API-v2-sample-code "Check out some sample code for these endpoints") diff --git a/x-api/users/lookup/migrate/standard-to-twitter-api-v2.mdx b/x-api/users/lookup/migrate/standard-to-twitter-api-v2.mdx index cb42ebddb..989a53378 100644 --- a/x-api/users/lookup/migrate/standard-to-twitter-api-v2.mdx +++ b/x-api/users/lookup/migrate/standard-to-twitter-api-v2.mdx @@ -1,229 +1,38 @@ ---- -title: v1 to v2 -sidebarTitle: v1 to v2 -keywords: ["v1.1 to v2 migration", "user lookup migration", "migrate user lookup", "standard to v2 user lookup", "v1 to v2 user lookup", "migration guide"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 GET users/show and GET users/lookup, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 users lookup endpoints. - -* **Similarities** - * OAuth 1.0a User Context - * Users per request limits -* **Differences** - * Endpoint URLs - * App and Project requirements - * Response data format - * Request parameters - -#### Similarities - -**OAuth 1.0a User Context authentication method** - -The standard endpoint supports [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2), while the new X API v2 users lookup endpoints supports both OAuth 1.0a User Context and [App only](/resources/fundamentals/authentication#oauth-2-0). Therefore, if you were previously using one of the standard v1.1 users lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see [this App only guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). - -**Users per request limits** - -The standard v1.1 GET users/lookup endpoint allows you to specify 100 users per request. This also goes for the GET /users and GET /users/by endpoints. To specify a full 100 users, you will need to pass the ids (GET /users) parameter or the username (GET /users/by) parameter as a query parameter, and include the list of user IDs/usernames in a comma-separated list. - - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * https://api.x.com/1.1/users/show (single-ID or username lookup) - * https://api.x.com/1.1/users/lookup (multi-ID or username lookup) -* X API v2 endpoint: - * https://api.x.com/2/users (multi-ID lookup) - * https://api.x.com/2/users/:id (single-ID lookup) - * https://api.x.com/2/users/by (multi-username lookup) - * https://api.x.com/2/users/by/username/:username (single-username lookup) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated to a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the user id , name, and username fields by default. To request any additional fields or objects, you wil need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any user fields that you request from this endpoint will return in the primary user object. Any expanded Post object and fields will return in an includes object within your response. You can then match any expanded objects back to the user object by matching the IDs located in both the user and the expanded Post object. - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. - - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array. -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like. -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values. - - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields -* A new reply_setting field, which shows you who can reply to a given Post - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| | | -| :--- | :--- | -| **Standard** | **X API v2** | -| user_id | ids | -| screen_name | username | - -There are also a set of standard users lookup request parameters **not** supported in X API v2: - -| Standard | Comment | -| :--- | :--- | -| include_entities | This parameter is used to remove the entities node from the Post payload. It has been replaced with the additive fields and expansions functionality. | - ---- - -### Code Examples - -The following examples show standard v1.1 endpoints and their v2 equivalents. - -**Single user lookup: v1.1 `GET users/show` → v2 `GET /users/by/username/:username`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/users/show.json?screen_name=XDevelopers' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/users/by/username/XDevelopers?user.fields=created_at,description,public_metrics' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/users/by/username/XDevelopers" - -params = { - "user.fields": "created_at,description,public_metrics" -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -print(response.json()) -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get user by username with additional fields -response = client.users.get_by_username( - "XDevelopers", - user_fields=["created_at", "description", "public_metrics"] -) - -print(f"Name: {response.data.name}") -print(f"Followers: {response.data.public_metrics.followers_count}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -const response = await client.users.getByUsername("XDevelopers", { - userFields: ["created_at", "description", "public_metrics"], -}); - -console.log(`Name: ${response.data?.name}`); -console.log(`Followers: ${response.data?.public_metrics?.followers_count}`); -``` - - - -**Multiple users lookup: v1.1 `GET users/lookup` → v2 `GET /users/by`** - - - -```bash cURL (v1.1) -curl --request GET \ - --url 'https://api.x.com/1.1/users/lookup.json?screen_name=XDevelopers,X,XAPI' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```bash cURL (v2) -curl --request GET \ - --url 'https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&user.fields=created_at,public_metrics' \ - --header 'Authorization: Bearer $ACCESS_TOKEN' -``` - -```python Python (v2) -import requests - -bearer_token = "YOUR_BEARER_TOKEN" -url = "https://api.x.com/2/users/by" - -params = { - "usernames": "XDevelopers,X,XAPI", - "user.fields": "created_at,public_metrics" -} - -headers = {"Authorization": f"Bearer {bearer_token}"} -response = requests.get(url, headers=headers, params=params) - -for user in response.json()["data"]: - print(f"{user['username']}: {user['public_metrics']['followers_count']} followers") -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_BEARER_TOKEN") - -# Get multiple users by usernames -response = client.users.get_users_by_usernames( - usernames=["XDevelopers", "X", "XAPI"], - user_fields=["created_at", "public_metrics"] -) - -for user in response.data: - print(f"{user.username}: {user.public_metrics.followers_count} followers") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" }); - -const response = await client.users.getUsersByUsernames({ - usernames: ["XDevelopers", "X", "XAPI"], - userFields: ["created_at", "public_metrics"], -}); - -response.data?.forEach((user) => { - console.log(`${user.username}: ${user.public_metrics?.followers_count} followers`); -}); -``` - - +--- +title: v1 to v2 +sidebarTitle: v1 to v2 +keywords: ["v1.1 to v2 migration", "user lookup migration", "migrate user lookup", "standard to v2 user lookup", "v1 to v2 user lookup", "migration guide"] + + +--- +import { Button } from '/snippets/button.mdx'; + +### Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 GET users/show and GET users/lookup, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 users lookup endpoints. + +* **Similarities** + * OAuth 1.0a User Context + * Users per request limits +* **Differences** + * Endpoint URLs + * App and Project requirements + * Response data format + * Request parameters + +#### Similarities + +**OAuth 1.0a User Context authentication method** + +The standard endpoint supports [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2), while the new X API v2 users lookup endpoints supports both OAuth 1.0a User Context and [App only](/resources/fundamentals/authentication#oauth-2-0). Therefore, if you were previously using one of the standard v1.1 users lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see [this App only guide](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). + +**Users per request limits** + +The standard v1.1 GET users/lookup endpoint allows you to specify 100 users per request. This also goes for the GET /users and GET /users/by endpoints. To specify a full 100 users, you will need to pass the ids (GET /users) parameter or the username (GET /users/by) parameter as a query parameter, and include the list of user IDs/usernames in a comma-separated list. + + +#### Differences + +**Endpoint URLs \ No newline at end of file diff --git a/x-api/users/mute-user.mdx b/x-api/users/mute-user.mdx index 2700f5d02..a171d6d19 100644 --- a/x-api/users/mute-user.mdx +++ b/x-api/users/mute-user.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/muting ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/mutes/integrate.mdx b/x-api/users/mutes/integrate.mdx index 73d0a8caf..34f19e60b 100644 --- a/x-api/users/mutes/integrate.mdx +++ b/x-api/users/mutes/integrate.mdx @@ -1,237 +1,236 @@ ---- -title: Integration Guide -sidebarTitle: Integration Guide -description: Key concepts and best practices for integrating mutes endpoints -keywords: ["mutes integration", "mute users integration", "mutes guide"] ---- - -import { Button } from '/snippets/button.mdx'; - -This guide covers the key concepts you need to integrate the mutes endpoints into your application. - ---- - -## Authentication - -Mutes endpoints require user authentication to access private mute lists: - -| Method | Description | -|:-------|:------------| -| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Recommended for new applications | -| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy support | - - -App-Only authentication is not supported. You must authenticate on behalf of a user. - - -### Required scopes (OAuth 2.0) - -| Scope | Required for | -|:------|:-------------| -| `mute.read` | Retrieving muted accounts | -| `mute.write` | Muting and unmuting accounts | -| `users.read` | Required with mute scopes | - ---- - -## Endpoints overview - -| Method | Endpoint | Description | -|:-------|:---------|:------------| -| GET | `/2/users/:id/muting` | Get list of muted accounts | -| POST | `/2/users/:id/muting` | Mute an account | -| DELETE | `/2/users/:source_user_id/muting/:target_user_id` | Unmute an account | - ---- - -## Fields and expansions - -### Default response - -```json -{ - "data": [ - { - "id": "1234567890", - "name": "Example User", - "username": "example" - } - ] -} -``` - -### Available fields - - -| Field | Description | -|:------|:------------| -| `created_at` | Account creation date | -| `description` | User bio | -| `profile_image_url` | Avatar URL | -| `public_metrics` | Follower/following counts | -| `verified` | Verification status | - - - -| Expansion | Description | -|:----------|:------------| -| `pinned_tweet_id` | User's pinned Post | - - -### Example with fields - - - -```bash cURL -curl "https://api.x.com/2/users/123456789/muting?\ -user.fields=username,verified,created_at&\ -max_results=100" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# Get muted users with additional fields -for page in client.users.get_muting( - user_id="123456789", - user_fields=["username", "verified", "created_at"], - max_results=100 -): - for user in page.data: - print(f"{user.username} - Verified: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -const paginator = client.users.getMuting("123456789", { - userFields: ["username", "verified", "created_at"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((user) => { - console.log(`${user.username} - Verified: ${user.verified}`); - }); -} -``` - - - ---- - -## Pagination - -For users with large mute lists, results are paginated: - - - -```bash cURL -# First request -curl "https://api.x.com/2/users/123/muting?max_results=100" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" - -# Subsequent request with pagination token -curl "https://api.x.com/2/users/123/muting?max_results=100&pagination_token=NEXT_TOKEN" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" -``` - -```python Python SDK -from xdk import Client - -client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") - -# The SDK handles pagination automatically -all_muted = [] - -for page in client.users.get_muting(user_id="123", max_results=100): - if page.data: - all_muted.extend(page.data) - -print(f"Muted {len(all_muted)} users") -``` - -```javascript JavaScript SDK -import { Client } from "@xdevplatform/xdk"; - -const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); - -async function getAllMutedUsers(userId) { - const allMuted = []; - - // The SDK handles pagination automatically - const paginator = client.users.getMuting(userId, { maxResults: 100 }); - - for await (const page of paginator) { - if (page.data) { - allMuted.push(...page.data); - } - } - - return allMuted; -} - -// Usage -const muted = await getAllMutedUsers("123"); -console.log(`Muted ${muted.length} users`); -``` - - - - - Learn more about pagination - - ---- - -## Behavior differences - -### Muting vs Blocking - -| Feature | Mute | Block | -|:--------|:-----|:------| -| See their Posts | No (hidden) | No | -| They see your Posts | Yes | No | -| They follow you | Yes (can follow) | No (removed) | -| They can DM you | Yes | No | -| Notification sent | No | No | - - -Muting is private — the muted user is not notified and cannot tell they've been muted. - - ---- - -## Error handling - -| Status | Error | Solution | -|:-------|:------|:---------| -| 400 | Invalid request | Check user ID format | -| 401 | Unauthorized | Verify access token | -| 403 | Forbidden | Check scopes and permissions | -| 404 | Not Found | User doesn't exist | -| 429 | Too Many Requests | Wait and retry | - ---- - -## Next steps - - - - Make your first mutes request - - - Block users instead of muting - - - Full endpoint documentation - - - Working code examples - - +--- +title: Integration Guide +sidebarTitle: Integration Guide +keywords: ["mutes integration", "mute users integration", "mutes guide"] +--- + +import { Button } from '/snippets/button.mdx'; + +This guide covers the key concepts you need to integrate the mutes endpoints into your application. + +--- + +## Authentication + +Mutes endpoints require user authentication to access private mute lists: + +| Method | Description | +|:-------|:------------| +| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Recommended for new applications | +| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy support | + + +App-Only authentication is not supported. You must authenticate on behalf of a user. + + +### Required scopes (OAuth 2.0) + +| Scope | Required for | +|:------|:-------------| +| `mute.read` | Retrieving muted accounts | +| `mute.write` | Muting and unmuting accounts | +| `users.read` | Required with mute scopes | + +--- + +## Endpoints overview + +| Method | Endpoint | Description | +|:-------|:---------|:------------| +| GET | `/2/users/:id/muting` | Get list of muted accounts | +| POST | `/2/users/:id/muting` | Mute an account | +| DELETE | `/2/users/:source_user_id/muting/:target_user_id` | Unmute an account | + +--- + +## Fields and expansions + +### Default response + +```json +{ + "data": [ + { + "id": "1234567890", + "name": "Example User", + "username": "example" + } + ] +} +``` + +### Available fields + + +| Field | Description | +|:------|:------------| +| `created_at` | Account creation date | +| `description` | User bio | +| `profile_image_url` | Avatar URL | +| `public_metrics` | Follower/following counts | +| `verified` | Verification status | + + + +| Expansion | Description | +|:----------|:------------| +| `pinned_tweet_id` | User's pinned Post | + + +### Example with fields + + + +```bash cURL +curl "https://api.x.com/2/users/123456789/muting?\ +user.fields=username,verified,created_at&\ +max_results=100" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") + +# Get muted users with additional fields +for page in client.users.get_muting( + user_id="123456789", + user_fields=["username", "verified", "created_at"], + max_results=100 +): + for user in page.data: + print(f"{user.username} - Verified: {user.verified}") +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); + +const paginator = client.users.getMuting("123456789", { + userFields: ["username", "verified", "created_at"], + maxResults: 100, +}); + +for await (const page of paginator) { + page.data?.forEach((user) => { + console.log(`${user.username} - Verified: ${user.verified}`); + }); +} +``` + + + +--- + +## Pagination + +For users with large mute lists, results are paginated: + + + +```bash cURL +# First request +curl "https://api.x.com/2/users/123/muting?max_results=100" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" + +# Subsequent request with pagination token +curl "https://api.x.com/2/users/123/muting?max_results=100&pagination_token=NEXT_TOKEN" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" +``` + +```python Python SDK +from xdk import Client + +client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN") + +# The SDK handles pagination automatically +all_muted = [] + +for page in client.users.get_muting(user_id="123", max_results=100): + if page.data: + all_muted.extend(page.data) + +print(f"Muted {len(all_muted)} users") +``` + +```javascript JavaScript SDK +import { Client } from "@xdevplatform/xdk"; + +const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" }); + +async function getAllMutedUsers(userId) { + const allMuted = []; + + // The SDK handles pagination automatically + const paginator = client.users.getMuting(userId, { maxResults: 100 }); + + for await (const page of paginator) { + if (page.data) { + allMuted.push(...page.data); + } + } + + return allMuted; +} + +// Usage +const muted = await getAllMutedUsers("123"); +console.log(`Muted ${muted.length} users`); +``` + + + + + Learn more about pagination + + +--- + +## Behavior differences + +### Muting vs Blocking + +| Feature | Mute | Block | +|:--------|:-----|:------| +| See their Posts | No (hidden) | No | +| They see your Posts | Yes | No | +| They follow you | Yes (can follow) | No (removed) | +| They can DM you | Yes | No | +| Notification sent | No | No | + + +Muting is private — the muted user is not notified and cannot tell they've been muted. + + +--- + +## Error handling + +| Status | Error | Solution | +|:-------|:------|:---------| +| 400 | Invalid request | Check user ID format | +| 401 | Unauthorized | Verify access token | +| 403 | Forbidden | Check scopes and permissions | +| 404 | Not Found | User doesn't exist | +| 429 | Too Many Requests | Wait and retry | + +--- + +## Next steps + + + + Make your first mutes request + + + Block users instead of muting + + + Full endpoint documentation + + + Working code examples + + diff --git a/x-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.mdx b/x-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.mdx index b0cfbeb91..f0711e187 100644 --- a/x-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.mdx +++ b/x-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.mdx @@ -1,195 +1,46 @@ ---- -title: Manage mutes -sidebarTitle: Manage mutes -keywords: ["manage mutes migration", "v1.1 to v2 manage mutes", "migrate manage mutes", "standard to v2 mutes", "mutes migration"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Manage mutes: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [POST mutes/users/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create) and [POST mutes/users/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage mutes endpoints. - -* **Similarities** - * OAuth 1.0a User Context -* **Differences** - * Endpoint URLs - * App and Project requirements - * HTTP methods - * Request parameters - - -#### Similarities - -**OAuth 1.0a User Context authentication method** - -Both the endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage mutes endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * POST https://api.x.com/1.1/mutes/users/create.json - (mute a user) - * POST https://api.x.com/1.1/mutes/users/destroy.json - (unmute a user) -* X API v2 endpoint: - * POST https://api.x.com/2/users/:id/muting - (mute a user) - * DELETE https://api.x.com/2/users/:source\_user\_id/muting/:target\_user\_id - (unmute a user) - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| Standard v1.1 | X API v2 | -| :--- | :--- | -| user_id | target\_user\_id | -| screen_name | No equivalent | - -Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters (for the POST endpoint) or path parameters (for the DELETE endpoint). - -Also, an id of the user muting a target user is not required when using the standard v1.1 endpoints since the access tokens passed with [OAuth 1.0a User Context](/resources/fundamentals/authentication) inferred which user was initiating the mute/unmute. - ---- - -## Code examples - -### Mute a user (v2) - - - -```bash cURL -curl -X POST "https://api.x.com/2/users/123456789/muting" \ - -H "Authorization: OAuth ..." \ - -H "Content-Type: application/json" \ - -d '{"target_user_id": "2244994945"}' -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/muting" -response = requests.post(url, auth=auth, json={"target_user_id": "2244994945"}) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Mute a user -response = client.users.mute( - source_user_id="123456789", - target_user_id="2244994945" -) -print(f"Muting: {response.data.muting}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Mute a user -const response = await client.users.mute("123456789", { - targetUserId: "2244994945", -}); -console.log(`Muting: ${response.data?.muting}`); -``` - - - -### Unmute a user (v2) - - - -```bash cURL -curl -X DELETE "https://api.x.com/2/users/123456789/muting/2244994945" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/muting/2244994945" -response = requests.delete(url, auth=auth) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Unmute a user -response = client.users.unmute( - source_user_id="123456789", - target_user_id="2244994945" -) -print(f"Muting: {response.data.muting}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Unmute a user -const response = await client.users.unmute("123456789", "2244994945"); -console.log(`Muting: ${response.data?.muting}`); -``` - - +--- +title: Manage mutes +sidebarTitle: Manage mutes +keywords: ["manage mutes migration", "v1.1 to v2 manage mutes", "migrate manage mutes", "standard to v2 mutes", "mutes migration"] + + +--- +import { Button } from '/snippets/button.mdx'; + +### Manage mutes: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [POST mutes/users/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create) and [POST mutes/users/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage mutes endpoints. + +* **Similarities** + * OAuth 1.0a User Context +* **Differences** + * Endpoint URLs + * App and Project requirements + * HTTP methods + * Request parameters + + +#### Similarities + +**OAuth 1.0a User Context authentication method** + +Both the endpoint versions support [OAuth 1.0a User Context](https://developer.x.com/content/developer-twitter/resources/fundamentals/authentication). Therefore, if you were previously using one of the standard v1.1 manage mutes endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * POST https://api.x.com/1.1/mutes/users/create.json + (mute a user) + * POST https://api.x.com/1.1/mutes/users/destroy.json + (unmute a user) +* X API v2 endpoint: + * POST https://api.x.com/2/users/:id/muting + (mute a user) + * DELETE https://api.x.com/2/users/:source\_user\_id/muting/:target\_user\_id + (unmute a user) + +**App and Project requirements** + +The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project \ No newline at end of file diff --git a/x-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.mdx b/x-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.mdx index a31e8f6da..9992a6c05 100644 --- a/x-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.mdx +++ b/x-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.mdx @@ -1,175 +1,46 @@ ---- -title: Mutes lookup -sidebarTitle: Mutes lookup -keywords: ["mutes lookup migration", "v1.1 to v2 mutes lookup", "migrate mutes lookup", "standard to v2 mutes", "mutes migration"] ---- - -import { Button } from '/snippets/button.mdx'; - -### Mutes lookup: Standard v1.1 compared to X API v2 - -If you have been working with the standard v1.1 [GET mutes/users/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids) and [GET mutes/users/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 mutes lookup endpoints. - -* **Similarities** - * Authentication -* **Differences** - * Endpoint URLs - - * Users per request limits - * App and Project requirements - * Response data formats - * Request parameters - -#### Similarities - -**Authentication** - -Both the standard v1.1 and X API v2 mutes lookup endpoints use [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 mutes lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.  - -#### Differences - -**Endpoint URLs** - -* Standard v1.1 endpoints: - * GET https://api.x.com/1.1/mutes/users/ids.json - (list of user IDs who the specified user muted) - * GET https://api.x.com/1.1/mutes/users/lists.json - (list of users who are muted by the specified user) -* X API v2 endpoint: - * GET https://api.x.com/2/users/:id/muting - (list of users who are muted by the specified user ID) -   - -**Users per request limits** - -The standard v1.1 endpoints allow you to return up to 5000 users per request. The new v2 endpoints allow you to return up to 1000 users per request. To return a full 1000 users, you will need to pass max_results=1000 as a query parameter; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request. -  - -**App and Project requirements** - -The X API v2 endpoints require that you use credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) when authenticating your requests. All X API v1.1 endpoints can use credentials from Apps or Apps associated with a project. - - -**Response data format** - -One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload. - -For the standard endpoints, you receive many of the response fields by default and then have the option to use parameters to identify which fields or sets of fields should return in the payload. - -The X API v2 version only delivers the user id, name, and username fields by default. To request any additional fields or objects, you will need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any user fields that you request from this endpoint will return in the primary user object. Any expanded Post object and fields will return an includes object within your response. You can then match any expanded objects back to the user object by matching the IDs located in both the user and the expanded Post object.  - -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  - -We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -  - -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. - -* At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  -* Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  -* Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like.  -* X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.  -   - -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: - -* A [conversation_id](/x-api/fundamentals/conversation-id) field -* Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities -* Several new [metrics](/x-api/fundamentals/metrics) fields  -* A new reply_setting field, which shows you who can reply to a given Post - -**Request parameters** - -The following standard v1.1 request parameters have equivalents in X API v2: - -| **Standard** | **X API v2** | -| :--- | :--- | -| stringify_ids | No equivalent | -| cursor | pagination_token | -| skip_status | No equivalent | - -There are also a set of standard v1.1 Mutes lookup request parameters **not** supported in X API v2: - -| Standard | Comment | -| :--- | :--- | -| include_entities | This parameter is used to remove the entities node from the Post payload. It has been replaced with additive fields and expansions functionality. | - ---- - -## Code examples - -### Get muted users (v2) - - - -```bash cURL -curl "https://api.x.com/2/users/123456789/muting?user.fields=username,verified&max_results=100" \ - -H "Authorization: OAuth ..." -``` - -```python Python -# Requires OAuth 1.0a User Context authentication -import requests -from requests_oauthlib import OAuth1 - -auth = OAuth1( - "API_KEY", "API_SECRET", - "ACCESS_TOKEN", "ACCESS_TOKEN_SECRET" -) - -url = "https://api.x.com/2/users/123456789/muting" -params = {"user.fields": "username,verified", "max_results": 100} - -response = requests.get(url, auth=auth, params=params) -print(response.json()) -``` - -```python Python SDK -from xdk import Client -from xdk.oauth1_auth import OAuth1 - -oauth1 = OAuth1( - api_key="YOUR_API_KEY", - api_secret="YOUR_API_SECRET", - access_token="YOUR_ACCESS_TOKEN", - access_token_secret="YOUR_ACCESS_TOKEN_SECRET" -) - -client = Client(auth=oauth1) - -# Get muted users with pagination -for page in client.users.get_muting( - "123456789", - user_fields=["username", "verified"], - max_results=100 -): - for user in page.data: - print(f"{user.username} - Verified: {user.verified}") -``` - -```javascript JavaScript SDK -import { Client, OAuth1 } from "@xdevplatform/xdk"; - -const oauth1 = new OAuth1({ - apiKey: "YOUR_API_KEY", - apiSecret: "YOUR_API_SECRET", - accessToken: "YOUR_ACCESS_TOKEN", - accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET", -}); - -const client = new Client({ oauth1 }); - -// Get muted users with pagination -const paginator = client.users.getMuting("123456789", { - userFields: ["username", "verified"], - maxResults: 100, -}); - -for await (const page of paginator) { - page.data?.forEach((user) => { - console.log(`${user.username} - Verified: ${user.verified}`); - }); -} -``` - - +--- +title: Mutes lookup +sidebarTitle: Mutes lookup +keywords: ["mutes lookup migration", "v1.1 to v2 mutes lookup", "migrate mutes lookup", "standard to v2 mutes", "mutes migration"] + + +--- +import { Button } from '/snippets/button.mdx'; + +### Mutes lookup: Standard v1.1 compared to X API v2 + +If you have been working with the standard v1.1 [GET mutes/users/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids) and [GET mutes/users/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list) endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 mutes lookup endpoints. + +* **Similarities** + * Authentication +* **Differences** + * Endpoint URLs + + * Users per request limits + * App and Project requirements + * Response data formats + * Request parameters + +#### Similarities + +**Authentication** + +Both the standard v1.1 and X API v2 mutes lookup endpoints use [OAuth 1.0a User Context](/resources/fundamentals/authentication#oauth-1-0a-2). Therefore, if you were previously using one of the standard v1.1 mutes lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.  + +#### Differences + +**Endpoint URLs** + +* Standard v1.1 endpoints: + * GET https://api.x.com/1.1/mutes/users/ids.json + (list of user IDs who the specified user muted) + * GET https://api.x.com/1.1/mutes/users/lists.json + (list of users who are muted by the specified user) +* X API v2 endpoint: + * GET https://api.x.com/2/users/:id/muting + (list of users who are muted by the specified user ID) +   + +**Users per request limits** + +The standard v1.1 endpoints allow you to return up to 5000 users per request. The new v2 endpoints allow you to return up to 1000 users per request. To return a full 1000 users, you w \ No newline at end of file diff --git a/x-api/users/mutes/migrate/overview.mdx b/x-api/users/mutes/migrate/overview.mdx index 121b7692f..f9a505baf 100644 --- a/x-api/users/mutes/migrate/overview.mdx +++ b/x-api/users/mutes/migrate/overview.mdx @@ -1,62 +1,62 @@ ---- -title: Overview -sidebarTitle: Overview -keywords: ["mutes migration", "mutes migrate", "v1.1 to v2 mutes", "mutes migration guide", "migrate mutes"] ---- - -import { Button } from '/snippets/button.mdx'; - -## Comparing X API’s mutes endpoints - -#### Mutes lookup - -The v2 mutes lookup endpoint will replace the standard [v1.1 GET mutes/users/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids) and [GET mutes/users/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list) endpoints. - -The following tables compare the standard v1.1 and X API v2 mute endpoints: -  - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | ******GET****** | ******GET****** | -| Host domain | ******https://api.x.com****** | ******https://api.x.com****** | -| Endpoint path | ******/1.1/mutes/users/ids.json******

/1.1/mutes/users/list.json | ******/2/users/:id/muting****** | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 15 requests per 15 min (per user) | 15 requests per 15 min (per user) | -| Data formats | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | -| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | - -#### Manage mutes - -The v2 manage mutes endpoints will replace the standard v1.1 [POST mutes/users/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create) and [POST mutes/users/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy) endpoints. - -The following tables compare the standard v1.1 and X API v2 mute endpoints: - -**Mute a user** - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | POST | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/mutes/users/create.json | /2/users/:id/muting | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 50 requests per 15 min | 50 requests per 15 min | -| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | - -**Unmute a user** - -The following tables compare the standard v1.1 and X API v2 unmute endpoints: - -| Description | Standard v1.1 | X API v2 | -| :--- | :--- | :--- | -| HTTP methods supported | POST | DELETE | -| Host domain | https://api.x.com | https://api.x.com | -| Endpoint path | /1.1/mutes/users/destroy.json | /2/users/:source\_user\_id/muting/:target\_user\_id | -| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | -| Default request [rate limits](/resources/fundamentals/rate-limits) | 50 requests per 15 min | 50 requests per 15 min | -| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | - -**Other migration resources** - -[Manage mutes: Standard v1.1 to X API v2](/x-api/users/mutes#manage-mutes-standard-v1-1-compared-to-x-api-v2) - -[X API migration hub](/x-api/migrate/overview) +--- +title: Overview +sidebarTitle: Overview +keywords: ["mutes migration", "mutes migrate", "v1.1 to v2 mutes", "mutes migration guide", "migrate mutes"] + + +import { Button } from '/snippets/button.mdx'; + +## Comparing X API’s mutes endpoints + +#### Mutes lookup + +The v2 mutes lookup endpoint will replace the standard [v1.1 GET mutes/users/ids](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids) and [GET mutes/users/list](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list) endpoints. + +The following tables compare the standard v1.1 and X API v2 mute endpoints: +  + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | ******GET****** | ******GET****** | +| Host domain | ******https://api.x.com****** | ******https://api.x.com****** | +| Endpoint path | ******/1.1/mutes/users/ids.json******

/1.1/mutes/users/list.json | ******/2/users/:id/muting****** | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 15 requests per 15 min (per user) | 15 requests per 15 min (per user) | +| Data formats | Standard v1.1 format | [X API v2 format](/x-api/fundamentals/data-dictionary) (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats)

To learn more about how to migrate from the Standard v1.1 format to the X API v2 format, please visit our [data formats migration guide](/x-api/migrate/data-format-migration). | +| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | + +#### Manage mutes + +The v2 manage mutes endpoints will replace the standard v1.1 [POST mutes/users/create](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create) and [POST mutes/users/destroy](https://developer.x.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy) endpoints. + +The following tables compare the standard v1.1 and X API v2 mute endpoints: + +**Mute a user** + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | POST | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/mutes/users/create.json | /2/users/:id/muting | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 50 requests per 15 min | 50 requests per 15 min | +| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | + +**Unmute a user** + +The following tables compare the standard v1.1 and X API v2 unmute endpoints: + +| Description | Standard v1.1 | X API v2 | +| :--- | :--- | :--- | +| HTTP methods supported | POST | DELETE | +| Host domain | https://api.x.com | https://api.x.com | +| Endpoint path | /1.1/mutes/users/destroy.json | /2/users/:source\_user\_id/muting/:target\_user\_id | +| [Authentication](/resources/fundamentals/authentication) | OAuth 1.0a User Context | OAuth 1.0a User Context

OAuth 2.0 Authorization Code with PKCE | +| Default request [rate limits](/resources/fundamentals/rate-limits) | 50 requests per 15 min | 50 requests per 15 min | +| Requires use of credentials from a [developer App](/resources/fundamentals/developer-apps) that is associated with a [Project](/resources/fundamentals/developer-apps) | | ✔️ | + +**Other migration resources** + +[Manage mutes: Standard v1.1 to X API v2](/x-api/users/mutes#manage-mutes-standard-v1-1-compared-to-x-api-v2) + +[X API migration hub](/x-api/migrate/overview) diff --git a/x-api/users/pin-list.mdx b/x-api/users/pin-list.mdx index 06b053043..ea308305f 100644 --- a/x-api/users/pin-list.mdx +++ b/x-api/users/pin-list.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/pinned_lists ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/repost-post.mdx b/x-api/users/repost-post.mdx index 8d6c6bed3..bf5a6462b 100644 --- a/x-api/users/repost-post.mdx +++ b/x-api/users/repost-post.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/retweets ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/search-users.mdx b/x-api/users/search-users.mdx index 04ae03548..8c735d93e 100644 --- a/x-api/users/search-users.mdx +++ b/x-api/users/search-users.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/users/search ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/unblock-dms.mdx b/x-api/users/unblock-dms.mdx index 93fa39097..fadadb2b7 100644 --- a/x-api/users/unblock-dms.mdx +++ b/x-api/users/unblock-dms.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/users/{id}/dm/unblock ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/unfollow-list.mdx b/x-api/users/unfollow-list.mdx index f9a9dd506..285a886fa 100644 --- a/x-api/users/unfollow-list.mdx +++ b/x-api/users/unfollow-list.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/followed_lists/{list_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/unfollow-user.mdx b/x-api/users/unfollow-user.mdx index fad80620a..6640aa553 100644 --- a/x-api/users/unfollow-user.mdx +++ b/x-api/users/unfollow-user.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{source_user_id}/following/{target_user_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/unlike-post.mdx b/x-api/users/unlike-post.mdx index 41a1df715..bf0bb9873 100644 --- a/x-api/users/unlike-post.mdx +++ b/x-api/users/unlike-post.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/likes/{tweet_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/unmute-user.mdx b/x-api/users/unmute-user.mdx index 1dca169c7..46e1ce21d 100644 --- a/x-api/users/unmute-user.mdx +++ b/x-api/users/unmute-user.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{source_user_id}/muting/{target_user_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/unpin-list.mdx b/x-api/users/unpin-list.mdx index fc06898f6..7c1b78f1f 100644 --- a/x-api/users/unpin-list.mdx +++ b/x-api/users/unpin-list.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/pinned_lists/{list_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/users/unrepost-post.mdx b/x-api/users/unrepost-post.mdx index 04622dc50..4835d8b14 100644 --- a/x-api/users/unrepost-post.mdx +++ b/x-api/users/unrepost-post.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/users/{id}/retweets/{source_tweet_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/webhooks/create-replay-job-for-webhook.mdx b/x-api/webhooks/create-replay-job-for-webhook.mdx index 914ba7e7f..c6cb52d7e 100644 --- a/x-api/webhooks/create-replay-job-for-webhook.mdx +++ b/x-api/webhooks/create-replay-job-for-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/webhooks/replay ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/webhooks/create-stream-link.mdx b/x-api/webhooks/create-stream-link.mdx index 821d78440..661db4d86 100644 --- a/x-api/webhooks/create-stream-link.mdx +++ b/x-api/webhooks/create-stream-link.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/tweets/search/webhooks/{webhook_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/webhooks/create-webhook.mdx b/x-api/webhooks/create-webhook.mdx index c170a7f50..45e0a0b07 100644 --- a/x-api/webhooks/create-webhook.mdx +++ b/x-api/webhooks/create-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: post /2/webhooks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/webhooks/delete-stream-link.mdx b/x-api/webhooks/delete-stream-link.mdx index 7cbe5ff36..3c5ce38ee 100644 --- a/x-api/webhooks/delete-stream-link.mdx +++ b/x-api/webhooks/delete-stream-link.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/tweets/search/webhooks/{webhook_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/webhooks/delete-webhook.mdx b/x-api/webhooks/delete-webhook.mdx index 32abbe065..9c2f9b1f3 100644 --- a/x-api/webhooks/delete-webhook.mdx +++ b/x-api/webhooks/delete-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: delete /2/webhooks/{webhook_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/webhooks/get-stream-links.mdx b/x-api/webhooks/get-stream-links.mdx index 95bc8e57b..826933a07 100644 --- a/x-api/webhooks/get-stream-links.mdx +++ b/x-api/webhooks/get-stream-links.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/tweets/search/webhooks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/webhooks/get-webhook.mdx b/x-api/webhooks/get-webhook.mdx index 51cec55d2..a686ad9be 100644 --- a/x-api/webhooks/get-webhook.mdx +++ b/x-api/webhooks/get-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: get /2/webhooks ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/x-api/webhooks/stream/introduction.mdx b/x-api/webhooks/stream/introduction.mdx index eb5d7503a..72ec3bf6d 100644 --- a/x-api/webhooks/stream/introduction.mdx +++ b/x-api/webhooks/stream/introduction.mdx @@ -2,7 +2,8 @@ title: Filtered Stream Webhooks API sidebarTitle: Introduction keywords: ["filtered stream webhooks", "stream webhooks", "webhook stream", "filtered stream webhook", "streaming webhooks", "webhook delivery"] ---- + +description: The filtered stream endpoint group enables developers to filter a stream of public Posts. This endpoint group’s functionality includes multiple endpoint...--- import { Button } from '/snippets/button.mdx'; diff --git a/x-api/webhooks/stream/quickstart.mdx b/x-api/webhooks/stream/quickstart.mdx index 71f965eba..18a795fa8 100644 --- a/x-api/webhooks/stream/quickstart.mdx +++ b/x-api/webhooks/stream/quickstart.mdx @@ -2,7 +2,8 @@ title: Quickstart sidebarTitle: Quickstart keywords: ["filtered stream webhooks quickstart", "webhook stream quickstart", "stream webhooks tutorial", "webhook stream guide"] ---- + +description: The v2 filtered stream webhooks API is similar to the [v2 filtered stream endpoint](/x-api/posts/filtered-stream/introduction) in terms of setting up th...--- ## Getting started with the filtered stream webhooks API diff --git a/x-api/webhooks/validate-webhook.mdx b/x-api/webhooks/validate-webhook.mdx index 952c5b6d0..d858a7b83 100644 --- a/x-api/webhooks/validate-webhook.mdx +++ b/x-api/webhooks/validate-webhook.mdx @@ -1,3 +1,4 @@ --- openapi: put /2/webhooks/{webhook_id} ---- \ No newline at end of file + +description: Reference documentation for the endpoint and related functionality.--- \ No newline at end of file diff --git a/xdks/llms.txt b/xdks/llms.txt new file mode 100644 index 000000000..c10309450 --- /dev/null +++ b/xdks/llms.txt @@ -0,0 +1,11 @@ +# X API SDKs (XDKs) + +> Official Python and TypeScript/JavaScript SDKs for the X API, including full client libraries, model definitions, pagination helpers, and streaming support. + +## Python XDK +- [Python XDK Overview](https://docs.x.com/xdks/python/llms.txt): Full reference for the Python SDK + +## TypeScript XDK +- [TypeScript XDK Overview](https://docs.x.com/xdks/typescript/llms.txt): Full reference for the TypeScript/JavaScript SDK + +See the individual nested llms.txt files for complete class, interface, and method documentation. diff --git a/xdks/python/authentication.mdx b/xdks/python/authentication.mdx index e71a6f2aa..e3941d955 100644 --- a/xdks/python/authentication.mdx +++ b/xdks/python/authentication.mdx @@ -1,7 +1,8 @@ --- title: Authentication sidebarTitle: Authentication ---- + +description: The X API requires authentication for all endpoints. The XDK supports three authentication methods: 1.--- The X API requires authentication for all endpoints. The XDK supports three authentication methods: 1. Bearer Token (app-only) 2. OAuth 2.0 with PKCE diff --git a/xdks/python/install.mdx b/xdks/python/install.mdx index 4d7c703fc..dcffe93bb 100644 --- a/xdks/python/install.mdx +++ b/xdks/python/install.mdx @@ -1,6 +1,8 @@ --- title: "Install" sidebarTitle: "Install" + +description: The XDK Python SDK is available directly from the GitHub repository and can be installed via `pip`. ## Prerequisites - Python 3.8 or higher. --- The XDK Python SDK is available directly from the GitHub repository and can be installed via `pip`. ## Prerequisites diff --git a/xdks/python/llms.txt b/xdks/python/llms.txt new file mode 100644 index 000000000..8a7bfc66d --- /dev/null +++ b/xdks/python/llms.txt @@ -0,0 +1,78 @@ +# Python XDK + +> Official Python SDK for the X API — clients, authentication, pagination, streaming, models, and complete endpoint coverage. + +## Core +- [Authentication](https://docs.x.com/xdks/python/authentication.md): The X API requires authentication for all endpoints. The XDK supports three authentication methods: 1. +- [Install](https://docs.x.com/xdks/python/install.md): The XDK Python SDK is available directly from the GitHub repository and can be installed via `pip`. ## Prerequisites - +- [Python XDK](https://docs.x.com/xdks/python/overview.md): Official Python client library for the X API v2. Supports OAuth, automatic pagination, real-time streaming, and all v2 +- [Pagination](https://docs.x.com/xdks/python/pagination.md): The X API uses pagination for endpoints that return multiple pages of results (e. +- [Quickstart](https://docs.x.com/xdks/python/quickstart.md): This example showcases how to quickly search for Posts using the XDK using Bearer Token authentication. ## Step 1: Ins +- [Streaming](https://docs.x.com/xdks/python/streaming.md): The X API supports real-time data via endpoints like the [Filtered Stream Endpoint](https://docs. + +## Reference +- [X API SDK Documentation](https://docs.x.com/xdks/python/reference/index.md) +- [xdk](https://docs.x.com/xdks/python/reference/modules.md) +- [AccountActivityClient](https://docs.x.com/xdks/python/reference/xdk.account_activity.client.md) +- [AccountActivityClient](https://docs.x.com/xdks/python/reference/xdk.account_activity.md) +- [Account_activity.Models](https://docs.x.com/xdks/python/reference/xdk.account_activity.models.md) +- [ActivityClient](https://docs.x.com/xdks/python/reference/xdk.activity.client.md) +- [ActivityClient](https://docs.x.com/xdks/python/reference/xdk.activity.md) +- [Activity.Models](https://docs.x.com/xdks/python/reference/xdk.activity.models.md) +- [Client](https://docs.x.com/xdks/python/reference/xdk.client.md) +- [CommunitiesClient](https://docs.x.com/xdks/python/reference/xdk.communities.client.md) +- [CommunitiesClient](https://docs.x.com/xdks/python/reference/xdk.communities.md) +- [Communities.Models](https://docs.x.com/xdks/python/reference/xdk.communities.models.md) +- [CommunityNotesClient](https://docs.x.com/xdks/python/reference/xdk.community_notes.client.md) +- [CommunityNotesClient](https://docs.x.com/xdks/python/reference/xdk.community_notes.md) +- [Community_notes.Models](https://docs.x.com/xdks/python/reference/xdk.community_notes.models.md) +- [ComplianceClient](https://docs.x.com/xdks/python/reference/xdk.compliance.client.md) +- [ComplianceClient](https://docs.x.com/xdks/python/reference/xdk.compliance.md) +- [Compliance.Models](https://docs.x.com/xdks/python/reference/xdk.compliance.models.md) +- [ConnectionsClient](https://docs.x.com/xdks/python/reference/xdk.connections.client.md) +- [ConnectionsClient](https://docs.x.com/xdks/python/reference/xdk.connections.md) +- [Connections.Models](https://docs.x.com/xdks/python/reference/xdk.connections.models.md) +- [DirectMessagesClient](https://docs.x.com/xdks/python/reference/xdk.direct_messages.client.md) +- [DirectMessagesClient](https://docs.x.com/xdks/python/reference/xdk.direct_messages.md) +- [Direct_messages.Models](https://docs.x.com/xdks/python/reference/xdk.direct_messages.models.md) +- [GeneralClient](https://docs.x.com/xdks/python/reference/xdk.general.client.md) +- [GeneralClient](https://docs.x.com/xdks/python/reference/xdk.general.md) +- [General.Models](https://docs.x.com/xdks/python/reference/xdk.general.models.md) +- [ListsClient](https://docs.x.com/xdks/python/reference/xdk.lists.client.md) +- [ListsClient](https://docs.x.com/xdks/python/reference/xdk.lists.md) +- [Lists.Models](https://docs.x.com/xdks/python/reference/xdk.lists.models.md) +- [Client](https://docs.x.com/xdks/python/reference/xdk.md) +- [MediaClient](https://docs.x.com/xdks/python/reference/xdk.media.client.md) +- [MediaClient](https://docs.x.com/xdks/python/reference/xdk.media.md) +- [Media.Models](https://docs.x.com/xdks/python/reference/xdk.media.models.md) +- [NewsClient](https://docs.x.com/xdks/python/reference/xdk.news.client.md) +- [NewsClient](https://docs.x.com/xdks/python/reference/xdk.news.md) +- [News.Models](https://docs.x.com/xdks/python/reference/xdk.news.models.md) +- [oauth1_auth](https://docs.x.com/xdks/python/reference/xdk.oauth1_auth.md) +- [OAuth2PKCEAuth](https://docs.x.com/xdks/python/reference/xdk.oauth2_auth.md) +- [paginator](https://docs.x.com/xdks/python/reference/xdk.paginator.md) +- [PostsClient](https://docs.x.com/xdks/python/reference/xdk.posts.client.md) +- [PostsClient](https://docs.x.com/xdks/python/reference/xdk.posts.md) +- [Posts.Models](https://docs.x.com/xdks/python/reference/xdk.posts.models.md) +- [SpacesClient](https://docs.x.com/xdks/python/reference/xdk.spaces.client.md) +- [SpacesClient](https://docs.x.com/xdks/python/reference/xdk.spaces.md) +- [Spaces.Models](https://docs.x.com/xdks/python/reference/xdk.spaces.models.md) +- [StreamClient](https://docs.x.com/xdks/python/reference/xdk.stream.client.md) +- [StreamClient](https://docs.x.com/xdks/python/reference/xdk.stream.md) +- [Stream.Models](https://docs.x.com/xdks/python/reference/xdk.stream.models.md) +- [streaming](https://docs.x.com/xdks/python/reference/xdk.streaming.md) +- [TrendsClient](https://docs.x.com/xdks/python/reference/xdk.trends.client.md) +- [TrendsClient](https://docs.x.com/xdks/python/reference/xdk.trends.md) +- [Trends.Models](https://docs.x.com/xdks/python/reference/xdk.trends.models.md) +- [UsageClient](https://docs.x.com/xdks/python/reference/xdk.usage.client.md) +- [UsageClient](https://docs.x.com/xdks/python/reference/xdk.usage.md) +- [Usage.Models](https://docs.x.com/xdks/python/reference/xdk.usage.models.md) +- [UsersClient](https://docs.x.com/xdks/python/reference/xdk.users.client.md) +- [UsersClient](https://docs.x.com/xdks/python/reference/xdk.users.md) +- [Users.Models](https://docs.x.com/xdks/python/reference/xdk.users.models.md) +- [WebhooksClient](https://docs.x.com/xdks/python/reference/xdk.webhooks.client.md) +- [WebhooksClient](https://docs.x.com/xdks/python/reference/xdk.webhooks.md) +- [Webhooks.Models](https://docs.x.com/xdks/python/reference/xdk.webhooks.models.md) + +## Full Documentation +- [llms-full.txt](https://docs.x.com/llms-full.txt) \ No newline at end of file diff --git a/xdks/python/overview.mdx b/xdks/python/overview.mdx index 6de58d7d6..a191308d8 100644 --- a/xdks/python/overview.mdx +++ b/xdks/python/overview.mdx @@ -1,6 +1,7 @@ --- title: Python XDK sidebarTitle: Overview +description: Official Python client library for the X API v2. Supports OAuth, automatic pagination, real-time streaming, and all v2 endpoints with a clean, high-level interface. --- The Python XDK (X Developer Kit) is our official client library for interacting with the X API v2 using Python. It allows developers to get started with our API quickly and build applications with it. It is generated based on our official [OpenAPI specification](https://api.x.com/2/openapi.json). It abstracts away low-level HTTP details while providing fine-grained control when needed. ## Key Features diff --git a/xdks/python/pagination.mdx b/xdks/python/pagination.mdx index 2da9bef29..638ce0a55 100644 --- a/xdks/python/pagination.mdx +++ b/xdks/python/pagination.mdx @@ -1,7 +1,8 @@ --- title: Pagination sidebarTitle: Pagination ---- + +description: The X API uses pagination for endpoints that return multiple pages of results (e.--- The X API uses pagination for endpoints that return multiple pages of results (e.g. timelines, search etc.). Each API call response includes a `meta` object with `result_count`, `previous_token`, and `next_token`. The XDK takes care of making multiple API calls using the `next_token` so developers can just specify how much data they are looking for without having to make multiple calls. The SDK simplifies this with: - **Built-in Iterators**: Use generator functions for seamless multi-page fetching. diff --git a/xdks/python/quickstart.mdx b/xdks/python/quickstart.mdx index 387923ecf..44a106db6 100644 --- a/xdks/python/quickstart.mdx +++ b/xdks/python/quickstart.mdx @@ -1,6 +1,8 @@ --- title: Quickstart sidebarTitle: Quickstart + +description: This example showcases how to quickly search for Posts using the XDK using Bearer Token authentication. ## Step 1: Install the SDK ```bash pip install xdk ``... --- This example showcases how to quickly search for Posts using the XDK using Bearer Token authentication. ## Step 1: Install the SDK diff --git a/xdks/python/streaming.mdx b/xdks/python/streaming.mdx index cc4c76bb4..587ee08f8 100644 --- a/xdks/python/streaming.mdx +++ b/xdks/python/streaming.mdx @@ -1,7 +1,8 @@ --- title: Streaming sidebarTitle: Streaming ---- + +description: The X API supports real-time data via endpoints like the [Filtered Stream Endpoint](https://docs.--- The X API supports real-time data via endpoints like the [Filtered Stream Endpoint](https://docs.x.com/x-api/posts/filtered-stream/introduction), delivering matching Posts as they occur. This requires making a persistent http connection. ## Setup and Basic Streaming ### Synchronous diff --git a/xdks/typescript/authentication.mdx b/xdks/typescript/authentication.mdx index d899767ad..672e5db51 100644 --- a/xdks/typescript/authentication.mdx +++ b/xdks/typescript/authentication.mdx @@ -1,7 +1,8 @@ --- title: "Authentication" sidebarTitle: "Authentication" ---- + +description: The TypeScript SDK supports multiple authentication methods for different use cases.--- The TypeScript SDK supports multiple authentication methods for different use cases. diff --git a/xdks/typescript/install.mdx b/xdks/typescript/install.mdx index c33180b27..71f7fa769 100644 --- a/xdks/typescript/install.mdx +++ b/xdks/typescript/install.mdx @@ -1,6 +1,8 @@ --- title: "Installation" sidebarTitle: "Installation" + +description: Get started with the TypeScript SDK for X API in your project. ## Install ```bash npm theme={null} npm install @xdevplatform/xdk ``` ```bash y... --- Get started with the TypeScript SDK for X API in your project. diff --git a/xdks/typescript/llms.txt b/xdks/typescript/llms.txt new file mode 100644 index 000000000..bc258e931 --- /dev/null +++ b/xdks/typescript/llms.txt @@ -0,0 +1,115 @@ +# TypeScript XDK + +> Official TypeScript/JavaScript SDK with full type safety, smart pagination, streaming, and exhaustive model definitions. + +## Core +- [Authentication](https://docs.x.com/xdks/typescript/authentication.md): The TypeScript SDK supports multiple authentication methods for different use cases. +- [Installation](https://docs.x.com/xdks/typescript/install.md): Get started with the TypeScript SDK for X API in your project. ## Install ```bash npm theme={null} npm i +- [TypeScript XDK](https://docs.x.com/xdks/typescript/overview.md): Official TypeScript/JavaScript SDK for the X API v2 with full type safety, automatic pagination, event-driven streamin +- [Pagination](https://docs.x.com/xdks/typescript/pagination.md): The SDK provides generic paginator utilities you can use with any endpoint that returns paginated responses. Methods r +- [Streaming](https://docs.x.com/xdks/typescript/streaming.md): The TypeScript SDK provides real-time streaming capabilities for live data feeds. Connect to real-time sampled posts: + +## Reference +- [X API SDK v2.152 - v0.4.0](https://docs.x.com/xdks/typescript/reference/modules.md) +- [AccountActivityClient](https://docs.x.com/xdks/typescript/reference/classes/AccountActivityClient.md) +- [ActivityClient](https://docs.x.com/xdks/typescript/reference/classes/ActivityClient.md) +- [ApiError](https://docs.x.com/xdks/typescript/reference/classes/ApiError.md) +- [Client](https://docs.x.com/xdks/typescript/reference/classes/Client.md) +- [CommunitiesClient](https://docs.x.com/xdks/typescript/reference/classes/CommunitiesClient.md) +- [CommunityNotesClient](https://docs.x.com/xdks/typescript/reference/classes/CommunityNotesClient.md) +- [ComplianceClient](https://docs.x.com/xdks/typescript/reference/classes/ComplianceClient.md) +- [ConnectionsClient](https://docs.x.com/xdks/typescript/reference/classes/ConnectionsClient.md) +- [DirectMessagesClient](https://docs.x.com/xdks/typescript/reference/classes/DirectMessagesClient.md) +- [EventPaginator](https://docs.x.com/xdks/typescript/reference/classes/EventPaginator.md) +- [GeneralClient](https://docs.x.com/xdks/typescript/reference/classes/GeneralClient.md) +- [HttpClient](https://docs.x.com/xdks/typescript/reference/classes/HttpClient.md) +- [ListsClient](https://docs.x.com/xdks/typescript/reference/classes/ListsClient.md) +- [MediaClient](https://docs.x.com/xdks/typescript/reference/classes/MediaClient.md) +- [NewsClient](https://docs.x.com/xdks/typescript/reference/classes/NewsClient.md) +- [Paginator](https://docs.x.com/xdks/typescript/reference/classes/Paginator.md) +- [PostPaginator](https://docs.x.com/xdks/typescript/reference/classes/PostPaginator.md) +- [PostsClient](https://docs.x.com/xdks/typescript/reference/classes/PostsClient.md) +- [SpacesClient](https://docs.x.com/xdks/typescript/reference/classes/SpacesClient.md) +- [StreamClient](https://docs.x.com/xdks/typescript/reference/classes/StreamClient.md) +- [TrendsClient](https://docs.x.com/xdks/typescript/reference/classes/TrendsClient.md) +- [UsageClient](https://docs.x.com/xdks/typescript/reference/classes/UsageClient.md) +- [UserPaginator](https://docs.x.com/xdks/typescript/reference/classes/UserPaginator.md) +- [UsersClient](https://docs.x.com/xdks/typescript/reference/classes/UsersClient.md) +- [WebhooksClient](https://docs.x.com/xdks/typescript/reference/classes/WebhooksClient.md) +- [Namespace: AccountActivity](https://docs.x.com/xdks/typescript/reference/modules/AccountActivity.md) +- [Namespace: Activity](https://docs.x.com/xdks/typescript/reference/modules/Activity.md) +- [Namespace: Communities](https://docs.x.com/xdks/typescript/reference/modules/Communities.md) +- [Namespace: CommunityNotes](https://docs.x.com/xdks/typescript/reference/modules/CommunityNotes.md) +- [Namespace: Compliance](https://docs.x.com/xdks/typescript/reference/modules/Compliance.md) +- [Namespace: Connections](https://docs.x.com/xdks/typescript/reference/modules/Connections.md) +- [Namespace: DirectMessages](https://docs.x.com/xdks/typescript/reference/modules/DirectMessages.md) +- [Namespace: General](https://docs.x.com/xdks/typescript/reference/modules/General.md) +- [Namespace: Lists](https://docs.x.com/xdks/typescript/reference/modules/Lists.md) +- [Namespace: Media](https://docs.x.com/xdks/typescript/reference/modules/Media.md) +- [Namespace: News](https://docs.x.com/xdks/typescript/reference/modules/News.md) +- [Namespace: Posts](https://docs.x.com/xdks/typescript/reference/modules/Posts.md) +- [Namespace: Schemas](https://docs.x.com/xdks/typescript/reference/modules/Schemas.md) +- [Namespace: Spaces](https://docs.x.com/xdks/typescript/reference/modules/Spaces.md) +- [Namespace: Stream](https://docs.x.com/xdks/typescript/reference/modules/Stream.md) +- [Namespace: Trends](https://docs.x.com/xdks/typescript/reference/modules/Trends.md) +- [Namespace: Usage](https://docs.x.com/xdks/typescript/reference/modules/Usage.md) +- [Namespace: Users](https://docs.x.com/xdks/typescript/reference/modules/Users.md) +- [Namespace: Webhooks](https://docs.x.com/xdks/typescript/reference/modules/Webhooks.md) +- [ApiResponse](https://docs.x.com/xdks/typescript/reference/interfaces/ApiResponse.md) +- [ClientConfig](https://docs.x.com/xdks/typescript/reference/interfaces/ClientConfig.md) +- [HttpClientRequestOptions](https://docs.x.com/xdks/typescript/reference/interfaces/HttpClientRequestOptions.md) +- [HttpResponse](https://docs.x.com/xdks/typescript/reference/interfaces/HttpResponse.md) +- [PaginatedResponse](https://docs.x.com/xdks/typescript/reference/interfaces/PaginatedResponse.md) +- [PaginationMeta](https://docs.x.com/xdks/typescript/reference/interfaces/PaginationMeta.md) +- [RequestOptions](https://docs.x.com/xdks/typescript/reference/interfaces/RequestOptions.md) +- [ActivityStreamingResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivityStreamingResponse.md) +- [ActivitySubscription](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscription.md) +- [ActivitySubscriptionCreateRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateRequest.md) +- [ActivitySubscriptionCreateResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionCreateResponse.md) +- [ActivitySubscriptionDeleteResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionDeleteResponse.md) +- [ActivitySubscriptionFilter](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionFilter.md) +- [ActivitySubscriptionGetResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionGetResponse.md) +- [ActivitySubscriptionUpdateRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateRequest.md) +- [ActivitySubscriptionUpdateResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ActivitySubscriptionUpdateResponse.md) +- [AddOrDeleteRulesResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AddOrDeleteRulesResponse.md) +- [AddRulesRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AddRulesRequest.md) +- [AllowDownloadStatus](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AllowDownloadStatus.md) +- [AltText](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AltText.md) +- [Analytics](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Analytics.md) +- [AppRulesCount](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AppRulesCount.md) +- [AudiencePolicy](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.AudiencePolicy.md) +- [BookmarkAddRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.BookmarkAddRequest.md) +- [BookmarkFolderPostsResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.BookmarkFolderPostsResponse.md) +- [BookmarkFoldersResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.BookmarkFoldersResponse.md) +- [BookmarkMutationResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.BookmarkMutationResponse.md) +- [CashtagFields](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CashtagFields.md) +- [ClientAppUsage](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ClientAppUsage.md) +- [Community](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Community.md) +- [ComplianceJob](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ComplianceJob.md) +- [Connection](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Connection.md) +- [ContentExpiration](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ContentExpiration.md) +- [ContextAnnotation](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ContextAnnotation.md) +- [ContextAnnotationDomainFields](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ContextAnnotationDomainFields.md) +- [ContextAnnotationEntityFields](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.ContextAnnotationEntityFields.md) +- [CreateAttachmentsMessageRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateAttachmentsMessageRequest.md) +- [CreateComplianceJobRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobRequest.md) +- [CreateComplianceJobResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateComplianceJobResponse.md) +- [CreateDmConversationRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateDmConversationRequest.md) +- [CreateDmEventResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateDmEventResponse.md) +- [CreateNoteRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateNoteRequest.md) +- [CreateNoteResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateNoteResponse.md) +- [CreateTextMessageRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.CreateTextMessageRequest.md) +- [DeleteDmResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DeleteDmResponse.md) +- [DeleteNoteResponse](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DeleteNoteResponse.md) +- [DeleteRulesRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DeleteRulesRequest.md) +- [DmEvent](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DmEvent.md) +- [DmMediaAttachment](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DmMediaAttachment.md) +- [DomainRestrictions](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.DomainRestrictions.md) +- [Engagement](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Engagement.md) +- [EntityIndicesInclusiveExclusive](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveExclusive.md) +- [EntityIndicesInclusiveInclusive](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.EntityIndicesInclusiveInclusive.md) +- [Error](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.Error.md) +- [EvaluateNoteRequest](https://docs.x.com/xdks/typescript/reference/interfaces/Schemas.EvaluateNoteRequest.md) + +## Full Documentation +- [llms-full.txt](https://docs.x.com/llms-full.txt) \ No newline at end of file diff --git a/xdks/typescript/overview.mdx b/xdks/typescript/overview.mdx index ab7185c45..52661e3bc 100644 --- a/xdks/typescript/overview.mdx +++ b/xdks/typescript/overview.mdx @@ -1,6 +1,7 @@ --- title: "TypeScript XDK" sidebarTitle: "Overview" +description: Official TypeScript/JavaScript SDK for the X API v2 with full type safety, automatic pagination, event-driven streaming, and support for all authentication methods. --- A comprehensive TypeScript SDK for the X API (formerly Twitter API) with advanced features including smart pagination, multiple authentication methods, real-time streaming, and full type safety. diff --git a/xdks/typescript/pagination.mdx b/xdks/typescript/pagination.mdx index 5b7ee0255..dc92ec4cd 100644 --- a/xdks/typescript/pagination.mdx +++ b/xdks/typescript/pagination.mdx @@ -1,7 +1,8 @@ --- title: "Pagination" sidebarTitle: "Pagination" ---- + +description: The SDK provides generic paginator utilities you can use with any endpoint that returns paginated responses. Methods return plain responses; you wrap th...--- The SDK provides generic paginator utilities you can use with any endpoint that returns paginated responses. Methods return plain responses; you wrap them with a paginator. diff --git a/xdks/typescript/streaming.mdx b/xdks/typescript/streaming.mdx index 6106fe661..cebaa6325 100644 --- a/xdks/typescript/streaming.mdx +++ b/xdks/typescript/streaming.mdx @@ -1,7 +1,8 @@ --- title: "Streaming" sidebarTitle: "Streaming" ---- + +description: The TypeScript SDK provides real-time streaming capabilities for live data feeds. Connect to real-time sampled posts: Consume the stream with async iter...--- The TypeScript SDK provides real-time streaming capabilities for live data feeds. From 6c45c4f6509ee90e3d52b296b27fa909b284bfbf Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Mon, 4 May 2026 20:24:02 -0700 Subject: [PATCH 31/38] docs: Major agent-readiness and Mintlify scorer improvements (Data Dictionary + final polish) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Split x-api/fundamentals/data-dictionary.mdx (125k → clean overview + dedicated reference) - Split x-ads-api/audiences.mdx (97k → 32k overview + 65k reference) - Added rich descriptions to Powerstream, Volume/Compliance Streams, XDK reference modules - Added smart client-side anchor redirect scripts on Audiences and Data Dictionary overviews (preserves old deep links) - Fixed frontmatter/import parsing issues from the splits - Updated docs.json navigation for all new reference pages - Bulk link fixes across the repo for moved anchors - Final regeneration of x-api/, enterprise-api/, x-ads-api/ llms.txt with all latest descriptions This continues the agent-scorer work: Page Size (multiple large pages split), LLMS TXT Freshness/Valid (richer indexes), link safety (redirects + scripts), and overall agent usability. All changes keep mintlify dev working cleanly. --- changelog.mdx | 4 +- docs.json | 8 +- .../migrate/standard-to-twitter-api-v2.mdx | 4 +- .../lists/list-members/integrate.mdx | 2 +- ...bers-lookup-standard-to-twitter-api-v2.mdx | 4 +- .../lists/list-tweets/integrate.mdx | 2 +- .../migrate/standard-to-twitter-api-v2.mdx | 4 +- .../lists/pinned-lists/integrate.mdx | 2 +- enterprise-api/llms.txt | 149 +- enterprise-api/media/introduction.mdx | 2 +- .../migrate/standard-to-twitter-api-v2.mdx | 6 +- enterprise-api/posts/retweets/integrate.mdx | 2 +- .../posts/volume-streams/introduction.mdx | 2 +- enterprise-api/spaces/introduction.mdx | 4 +- .../webhooks/stream/introduction.mdx | 2 +- tutorials/explore-a-users-posts.mdx | 2 +- ...ing-started-with-r-and-v2-of-the-x-api.mdx | 2 +- x-ads-api/audiences.mdx | 1355 +------- x-ads-api/audiences/reference.mdx | 1336 ++++++++ x-ads-api/campaign-management.mdx | 37 +- x-ads-api/campaign-management/reference.mdx | 13 +- x-ads-api/creatives.mdx | 2986 +---------------- x-ads-api/creatives/reference.mdx | 2939 ++++++++++++++++ .../hierarchy-and-terminology.mdx | 2 +- x-ads-api/fundamentals/versioning.mdx | 6 +- x-ads-api/llms.txt | 52 +- x-api/compliance/streams/introduction.mdx | 1 + .../fundamentals/data-dictionary.mdx | 2 +- x-api/fundamentals/data-dictionary.mdx | 1792 +--------- .../data-dictionary/reference.mdx | 1780 ++++++++++ x-api/fundamentals/fields.mdx | 10 +- .../migrate/standard-to-twitter-api-v2.mdx | 4 +- x-api/lists/list-members/integrate.mdx | 2 +- x-api/lists/list-tweets/integrate.mdx | 2 +- .../migrate/standard-to-twitter-api-v2.mdx | 4 +- x-api/lists/pinned-lists/integrate.mdx | 2 +- x-api/llms.txt | 142 +- x-api/media/introduction.mdx | 2 +- x-api/migrate/overview.mdx | 8 +- .../migrate/standard-to-twitter-api-v2.mdx | 6 +- x-api/posts/retweets/integrate.mdx | 2 +- x-api/posts/volume-streams/introduction.mdx | 3 +- x-api/powerstream/introduction.mdx | 1 + x-api/powerstream/operators.mdx | 1 + x-api/spaces/introduction.mdx | 4 +- x-api/users/blocks/migrate.mdx | 6 +- x-api/webhooks/stream/introduction.mdx | 2 +- .../web-intents/image-resources.mdx | 2 +- xdks/python/reference/modules.mdx | 1 + xdks/typescript/reference/modules.mdx | 1 + 50 files changed, 6425 insertions(+), 6282 deletions(-) create mode 100644 x-ads-api/audiences/reference.mdx create mode 100644 x-ads-api/creatives/reference.mdx create mode 100644 x-api/fundamentals/data-dictionary/reference.mdx diff --git a/changelog.mdx b/changelog.mdx index c11af08a1..bca4ede02 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -1,6 +1,6 @@ --- title: Changelog -description: "The X Developer Platform is updated frequently with new functionality and products to better suit your needs. We will be documenting all changes made to the platform's products via this resource and the @API X account." +description: Comprehensive changelog documenting every update to the X API v2, Enterprise APIs, Ads API, SDKs, streaming, compliance, webhooks, and developer platform tools. sidebarTitle: Overview keywords: ["changelog", "API updates", "release notes", "what's new", "API changes", "version updates", "platform updates"] --- @@ -866,7 +866,7 @@ We have fully retired the Terms of Service and Privacy Endpoints. The current st ### Changes to User Object Fields Today some user object fields, including user.lang, will start returning 'null' for updated metadata fields previously announced in our [forum post](https://devcommunity.x.com/t/upcoming-changes-to-user-object-and-get-users-suggestions-endpoints/124732). - Developers can learn about this change through our [documentation.](/x-api/fundamentals/data-dictionary#user) + Developers can learn about this change through our [documentation.](/x-api/fundamentals/data-dictionary/reference#user) diff --git a/docs.json b/docs.json index efdb7fc60..909f1fd44 100644 --- a/docs.json +++ b/docs.json @@ -171,6 +171,7 @@ "group": "Fundamentals", "pages": [ "x-api/fundamentals/data-dictionary", + "x-api/fundamentals/data-dictionary/reference", "x-api/fundamentals/fields", "x-api/fundamentals/expansions", "x-api/fundamentals/post-annotations", @@ -1026,6 +1027,7 @@ "x-ads-api/tools-and-libraries", "x-ads-api/analytics", "x-ads-api/audiences", + "x-ads-api/audiences/reference", { "group": "Campaign Management", "pages": [ @@ -1034,7 +1036,8 @@ ] }, "x-ads-api/catalog-management", - "x-ads-api/creatives" + "x-ads-api/creatives", + "x-ads-api/creatives/reference" ] }, { @@ -1263,6 +1266,9 @@ ] }, "redirects": [ + { "source": "/enterprise-api/enterprise-gnip-2.0/:path*", "destination": "/x-api/enterprise-gnip-2.0/:path*", "permanent": true }, + { "source": "/enterprise-api/fundamentals/:path*", "destination": "/x-api/fundamentals/:path*", "permanent": true }, + { "source": "/enterprise-api/migrate/:path*", "destination": "/x-api/migrate/:path*", "permanent": true }, {"source": "/updates/changelog", "destination": "/changelog"}, {"source": "/status/status", "destination": "/status"}, {"source": "/status/incident", "destination": "/incidents"}, diff --git a/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx index fe5bd6ef1..9ab4289a7 100644 --- a/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.mdx @@ -91,11 +91,11 @@ Here are examples of possible List fields and expansions: | /2/lists/:id | owner_id | | /2/users/:id/owned_lists | owner_id | -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  +We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary/reference#how-to-use-fields-and-expansions).  We have also put together a [data format migration guide](/x-api/migrate/data-format-migration) that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you with the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. +In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary/reference#tweet) and [user](/x-api/fundamentals/data-dictionary/reference#user) objects. * At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  diff --git a/enterprise-api/lists/list-members/integrate.mdx b/enterprise-api/lists/list-members/integrate.mdx index 632f9aa81..93eab0bc4 100644 --- a/enterprise-api/lists/list-members/integrate.mdx +++ b/enterprise-api/lists/list-members/integrate.mdx @@ -69,7 +69,7 @@ The X API v2 GET endpoint allows users to select exactly which data they want to The `fields` parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. List members lookup delivers user objects primarily. By default, the user object returns id, name, and username fields. To receive additional fields such as `user.created_at` or `user.description`, you will have to specifically request those using a user.fields parameter. -We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). +We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary/reference#how-to-use-fields-and-expansions). The chart below shows the field and expansions available for each lookup endpoint: diff --git a/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx b/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx index 6ea32f009..ed624ea2b 100644 --- a/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx +++ b/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.mdx @@ -93,11 +93,11 @@ Here are examples of possible List fields and expansions: | /2/lists/:id/members | pinned\_tweet\_id | | /2/users/:id/list_memberships | owner_id | -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  +We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary/reference#how-to-use-fields-and-expansions).  We have also put together a [data format migration guide](/x-api/migrate/data-format-migration) that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you with the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.  -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. +In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary/reference#tweet) and [user](/x-api/fundamentals/data-dictionary/reference#user) objects. * At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  diff --git a/enterprise-api/lists/list-tweets/integrate.mdx b/enterprise-api/lists/list-tweets/integrate.mdx index 14e0c9c76..388c865ed 100644 --- a/enterprise-api/lists/list-tweets/integrate.mdx +++ b/enterprise-api/lists/list-tweets/integrate.mdx @@ -68,7 +68,7 @@ The X API v2 GET endpoint allows users to select exactly which data they want to The `fields` parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. This endpoint delivers Post objects primarily. By default, the Post object returns the `id`, and `text` fields. To receive additional fields such as `tweet.created_at` or `tweet.lang`, you will have to specifically request those using a fields parameter. -We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). +We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary/reference#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). The chart below shows the field and expansions available for the lookup endpoint: diff --git a/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx index 1fa4a0b70..689426cba 100644 --- a/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.mdx @@ -78,11 +78,11 @@ Here are examples of possible Post fields and expansions: | **Endpoint** | **Expansion** | | /2/lists/:id/tweets | author_id | -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). +We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary/reference#how-to-use-fields-and-expansions). We have also put together a [data format migration guide](/x-api/migrate/data-format-migration) that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields. -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary#tweet) and [user](/x-api/fundamentals/data-dictionary#user) objects. +In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including [Post](/x-api/fundamentals/data-dictionary/reference#tweet) and [user](/x-api/fundamentals/data-dictionary/reference#user) objects. * At the JSON root level, the standard endpoints return Post objects in a **statuses** array, while X API v2 returns a **data** array. diff --git a/enterprise-api/lists/pinned-lists/integrate.mdx b/enterprise-api/lists/pinned-lists/integrate.mdx index 999689256..c7f74aaba 100644 --- a/enterprise-api/lists/pinned-lists/integrate.mdx +++ b/enterprise-api/lists/pinned-lists/integrate.mdx @@ -64,7 +64,7 @@ The X API v2 GET endpoint allows users to select exactly which data they want to The `fields` parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. This endpoint delivers user objects primarily. By default, the List object returns the `id`, and `name` fields. To receive additional fields such as `list.created_at` or `list.description`, you will have to specifically request those using a fields parameter. -We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). +We've added a guide on using [fields and expansions](/x-api/fundamentals/data-dictionary/reference#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). The chart below shows the field and expansions available for the lookup endpoint: diff --git a/enterprise-api/llms.txt b/enterprise-api/llms.txt index 21a3b57e6..a1446ba95 100644 --- a/enterprise-api/llms.txt +++ b/enterprise-api/llms.txt @@ -1,8 +1,8 @@ # Enterprise APIs -> Enterprise-grade APIs: Account Activity webhooks, X Activity (XAA), GNIP 2.0 PowerTrack, historical search, compliance streams, and more. +> Account Activity, X Activity, GNIP, historical data, compliance and enterprise X APIs. -## Core +## Main - [Enterprise API](https://docs.x.com/enterprise-api/introduction.md): Enterprise-grade access to X's full firehose, volume streams, and dedicated support - [Tools And Libraries](https://docs.x.com/enterprise-api/tools-and-libraries.md) - [What to Build](https://docs.x.com/enterprise-api/what-to-build.md): Ideas and inspiration for building with the X API @@ -16,7 +16,7 @@ - [V2 Account Activity API](https://docs.x.com/enterprise-api/account-activity/introduction.md): Receive real-time account activity events via webhooks - [Quickstart](https://docs.x.com/enterprise-api/account-activity/quickstart.md): Set up Account Activity API subscriptions and start receiving real-time events - [Validate Subscription](https://docs.x.com/enterprise-api/account-activity/validate-subscription.md): Reference documentation for the endpoint and related functionality. -- [v2 Account Activity API Migration Guide](https://docs.x.com/enterprise-api/account-activity/migrate/overview.md): This guide helps you migrate from the legacy Enterprise Account Activity API to the V2 Account Activity API. The core +- [v2 Account Activity API Migration Guide](https://docs.x.com/enterprise-api/account-activity/migrate/overview.md) ## Activity - [Activity Stream](https://docs.x.com/enterprise-api/activity/activity-stream.md): Reference documentation for the endpoint and related functionality. @@ -24,7 +24,7 @@ - [Deletes X Activity Subscription](https://docs.x.com/enterprise-api/activity/deletes-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. - [Get X Activity Subscriptions](https://docs.x.com/enterprise-api/activity/get-x-activity-subscriptions.md): Reference documentation for the endpoint and related functionality. - [Introduction](https://docs.x.com/enterprise-api/activity/introduction.md): The X Activity API (XAA) endpoint group allows developers to tap in to activity events happening on the X Platform. A -- [Quickstart](https://docs.x.com/enterprise-api/activity/quickstart.md): This guide explains how to subscribe for and receive events using the X Activity API endpoints. There generally 3 step +- [Quickstart](https://docs.x.com/enterprise-api/activity/quickstart.md) - [Update X Activity Subscription](https://docs.x.com/enterprise-api/activity/update-x-activity-subscription.md): Reference documentation for the endpoint and related functionality. ## Bookmarks @@ -70,8 +70,8 @@ - [Create Compliance Job](https://docs.x.com/enterprise-api/compliance/create-compliance-job.md): Reference documentation for the endpoint and related functionality. - [Get Compliance Job By Id](https://docs.x.com/enterprise-api/compliance/get-compliance-job-by-id.md): Reference documentation for the endpoint and related functionality. - [Get Compliance Jobs](https://docs.x.com/enterprise-api/compliance/get-compliance-jobs.md): Reference documentation for the endpoint and related functionality. -- [Introduction](https://docs.x.com/enterprise-api/compliance/streams/introduction.md): X is committed to our community of developers who build with the X API. As part of this commitment, we aim to make our -- [Integration guide](https://docs.x.com/enterprise-api/compliance/batch-compliance/integrate.md): When using the Batch compliance endpoints, developers can batch upload large amounts of X data and understand what act +- [Introduction](https://docs.x.com/enterprise-api/compliance/streams/introduction.md) +- [Integration guide](https://docs.x.com/enterprise-api/compliance/batch-compliance/integrate.md) - [Batch Compliance](https://docs.x.com/enterprise-api/compliance/batch-compliance/introduction.md): Check compliance status for Posts and users in bulk - [Quickstart](https://docs.x.com/enterprise-api/compliance/batch-compliance/quickstart.md): Create and run a batch compliance job @@ -93,11 +93,11 @@ - [Get Dm Events For A Dm Conversation](https://docs.x.com/enterprise-api/direct-messages/get-dm-events-for-a-dm-conversation.md): Reference documentation for the endpoint and related functionality. - [Get Dm Events](https://docs.x.com/enterprise-api/direct-messages/get-dm-events.md): Reference documentation for the endpoint and related functionality. - [Introduction](https://docs.x.com/enterprise-api/direct-messages/blocks/introduction.md): The manage DM blocks endpoints enable you to block or unblock a specified account on behalf of an authenticated user. -- [Integration Guide](https://docs.x.com/enterprise-api/direct-messages/lookup/integrate.md): Key concepts and best practices for integrating DM lookup endpoints +- [Integration Guide](https://docs.x.com/enterprise-api/direct-messages/lookup/integrate.md) - [Direct Messages Lookup](https://docs.x.com/enterprise-api/direct-messages/lookup/introduction.md): Retrieve Direct Message events and conversations - [Migration guide](https://docs.x.com/enterprise-api/direct-messages/lookup/migrate.md): 1 and v2 versions of the Direct Messages endpoints provide methods for looking up Direct Message events. - [Quickstart](https://docs.x.com/enterprise-api/direct-messages/lookup/quickstart.md): Retrieve Direct Message events and conversations -- [Integration Guide](https://docs.x.com/enterprise-api/direct-messages/manage/integrate.md): Key concepts and best practices for sending Direct Messages +- [Integration Guide](https://docs.x.com/enterprise-api/direct-messages/manage/integrate.md) - [Manage Direct Messages](https://docs.x.com/enterprise-api/direct-messages/manage/introduction.md): Send and delete Direct Messages - [Migration guide](https://docs.x.com/enterprise-api/direct-messages/manage/migrate.md): 1 and v2 versions of the Direct Messages endpoints provide methods for creating Direct Message messages. - [Quickstart](https://docs.x.com/enterprise-api/direct-messages/manage/quickstart.md): Send Direct Messages and create group conversations @@ -113,43 +113,43 @@ - [Enterprise Pricing](https://docs.x.com/enterprise-api/getting-started/pricing.md): Custom Enterprise pricing for the X API ## Lists -- [Add List Member](https://docs.x.com/enterprise-api/lists/add-list-member.md): Reference documentation for the endpoint and related functionality. -- [Create List](https://docs.x.com/enterprise-api/lists/create-list.md): Reference documentation for the endpoint and related functionality. -- [Delete List](https://docs.x.com/enterprise-api/lists/delete-list.md): Reference documentation for the endpoint and related functionality. -- [Get List By Id](https://docs.x.com/enterprise-api/lists/get-list-by-id.md): Reference documentation for the endpoint and related functionality. -- [Get List Followers](https://docs.x.com/enterprise-api/lists/get-list-followers.md): Reference documentation for the endpoint and related functionality. -- [Get List Members](https://docs.x.com/enterprise-api/lists/get-list-members.md): Reference documentation for the endpoint and related functionality. -- [Get List Posts](https://docs.x.com/enterprise-api/lists/get-list-posts.md): Reference documentation for the endpoint and related functionality. -- [Remove List Member](https://docs.x.com/enterprise-api/lists/remove-list-member.md): Reference documentation for the endpoint and related functionality. -- [Update List](https://docs.x.com/enterprise-api/lists/update-list.md): Reference documentation for the endpoint and related functionality. -- [Integration guide](https://docs.x.com/enterprise-api/lists/list-tweets/integrate.md): This page covers tools and key concepts for integrating the List Posts lookup endpoint. +- [Add List Member](https://docs.x.com/enterprise-api/lists/add-list-member.md) +- [Create List](https://docs.x.com/enterprise-api/lists/create-list.md) +- [Delete List](https://docs.x.com/enterprise-api/lists/delete-list.md) +- [Get List By Id](https://docs.x.com/enterprise-api/lists/get-list-by-id.md) +- [Get List Followers](https://docs.x.com/enterprise-api/lists/get-list-followers.md) +- [Get List Members](https://docs.x.com/enterprise-api/lists/get-list-members.md) +- [Get List Posts](https://docs.x.com/enterprise-api/lists/get-list-posts.md) +- [Remove List Member](https://docs.x.com/enterprise-api/lists/remove-list-member.md) +- [Update List](https://docs.x.com/enterprise-api/lists/update-list.md) +- [Integration guide](https://docs.x.com/enterprise-api/lists/list-tweets/integrate.md) - [List Posts](https://docs.x.com/enterprise-api/lists/list-tweets/introduction.md): Retrieve Posts from a List's timeline - [Quickstart](https://docs.x.com/enterprise-api/lists/list-tweets/quickstart.md): Get Posts from a List timeline -- [Overview](https://docs.x.com/enterprise-api/lists/list-tweets/migrate/overview.md): The v2 List Posts lookup endpoint will replace the standard v1. 1 [GET lists/statuses](https://developer. -- [v1 to v2](https://docs.x.com/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET lists/statuses](https://developer. -- [Integration guide](https://docs.x.com/enterprise-api/lists/list-members/integrate.md): This page covers tools and key concepts for integrating the List members endpoints. +- [Overview](https://docs.x.com/enterprise-api/lists/list-tweets/migrate/overview.md) +- [v1 to v2](https://docs.x.com/enterprise-api/lists/list-tweets/migrate/standard-to-twitter-api-v2.md) +- [Integration guide](https://docs.x.com/enterprise-api/lists/list-members/integrate.md) - [List Members](https://docs.x.com/enterprise-api/lists/list-members/introduction.md): View, add, and remove members from Lists - [List Members Lookup](https://docs.x.com/enterprise-api/lists/list-members/quickstart/list-members-lookup.md): Get members of a List - [Manage List Members](https://docs.x.com/enterprise-api/lists/list-members/quickstart/manage-list-members.md): Add and remove members from a List - [List Members Overview](https://docs.x.com/enterprise-api/lists/list-members/quickstart/overview.md): Get started with List members endpoints -- [List members lookup](https://docs.x.com/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET lists/members](https://developer. -- [Manage list members](https://docs.x.com/enterprise-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST lists/members/create](https://developer. -- [Overview](https://docs.x.com/enterprise-api/lists/list-members/migrate/overview.md): The v2 List members endpoint group will replace the standard v1. 1 [GET lists/members](https://developer. -- [Integration guide](https://docs.x.com/enterprise-api/lists/pinned-lists/integrate.md): This page covers tools and key concepts for integrating the pinned Lists endpoints. +- [List members lookup](https://docs.x.com/enterprise-api/lists/list-members/migrate/list-members-lookup-standard-to-twitter-api-v2.md) +- [Manage list members](https://docs.x.com/enterprise-api/lists/list-members/migrate/manage-list-members-standard-to-twitter-api-v2.md) +- [Overview](https://docs.x.com/enterprise-api/lists/list-members/migrate/overview.md) +- [Integration guide](https://docs.x.com/enterprise-api/lists/pinned-lists/integrate.md) - [Pinned Lists](https://docs.x.com/enterprise-api/lists/pinned-lists/introduction.md): View and manage pinned Lists - [Manage Pinned Lists](https://docs.x.com/enterprise-api/lists/pinned-lists/quickstart/manage-pinned-lists.md): Pin and unpin Lists - [Pinned Lists Overview](https://docs.x.com/enterprise-api/lists/pinned-lists/quickstart/overview.md): Get started with pinned List endpoints - [Pinned Lists Lookup](https://docs.x.com/enterprise-api/lists/pinned-lists/quickstart/pinned-list-lookup.md): Get a user's pinned Lists -- [Integration guide](https://docs.x.com/enterprise-api/lists/manage-lists/integrate.md): This page covers tools and key concepts for integrating the Lists endpoints. +- [Integration guide](https://docs.x.com/enterprise-api/lists/manage-lists/integrate.md) - [Manage Lists](https://docs.x.com/enterprise-api/lists/manage-lists/introduction.md): Create, update, and delete Lists - [Quickstart](https://docs.x.com/enterprise-api/lists/manage-lists/quickstart.md): Create, update, and delete Lists -- [Overview](https://docs.x.com/enterprise-api/lists/manage-lists/migrate/overview.md): The v2 manage Lists endpoints will eventually replace [POST lists/create](https://developer. -- [v1 to v2](https://docs.x.com/enterprise-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST lists/create](https://developer. -- [Integration Guide](https://docs.x.com/enterprise-api/lists/list-lookup/integrate.md): Key concepts and best practices for integrating List lookup +- [Overview](https://docs.x.com/enterprise-api/lists/manage-lists/migrate/overview.md) +- [v1 to v2](https://docs.x.com/enterprise-api/lists/manage-lists/migrate/standard-to-twitter-api-v2.md) +- [Integration Guide](https://docs.x.com/enterprise-api/lists/list-lookup/integrate.md) - [List Lookup](https://docs.x.com/enterprise-api/lists/list-lookup/introduction.md): Retrieve List details by ID or get Lists owned by a user - [Quickstart](https://docs.x.com/enterprise-api/lists/list-lookup/quickstart.md): Look up Lists by ID or owner -- [Overview](https://docs.x.com/enterprise-api/lists/list-lookup/migrate/overview.md): The v2 List lookup endpoint group will replace the standard v1. 1 [GET lists/show](https://developer. -- [v1 to v2](https://docs.x.com/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET lists/show](https://developer. +- [Overview](https://docs.x.com/enterprise-api/lists/list-lookup/migrate/overview.md) +- [v1 to v2](https://docs.x.com/enterprise-api/lists/list-lookup/migrate/standard-to-twitter-api-v2.md) ## Marketplace - [Get Marketplace Handle Availability](https://docs.x.com/enterprise-api/marketplace/get-marketplace-handle-availability.md): Reference documentation for the endpoint and related functionality. @@ -193,38 +193,38 @@ - [Hide Reply](https://docs.x.com/enterprise-api/posts/hide-reply.md): Reference documentation for the endpoint and related functionality. - [Search All Posts](https://docs.x.com/enterprise-api/posts/search-all-posts.md): Reference documentation for the endpoint and related functionality. - [Search Recent Posts](https://docs.x.com/enterprise-api/posts/search-recent-posts.md): Reference documentation for the endpoint and related functionality. -- [Introduction](https://docs.x.com/enterprise-api/posts/volume-streams/introduction.md): * 1% sampled stream. * 10% sampled stream. -- [Integration guide](https://docs.x.com/enterprise-api/posts/retweets/integrate.md): This page covers tools and key concepts for integrating the Retweet endpoints. +- [Introduction](https://docs.x.com/enterprise-api/posts/volume-streams/introduction.md) +- [Integration guide](https://docs.x.com/enterprise-api/posts/retweets/integrate.md) - [Retweets](https://docs.x.com/enterprise-api/posts/retweets/introduction.md): Retweet and undo retweets, and retrieve retweet information - [Manage Retweets](https://docs.x.com/enterprise-api/posts/retweets/quickstart/manage-retweets.md): Retweet and undo Retweets using the X API - [Retweets Lookup](https://docs.x.com/enterprise-api/posts/retweets/quickstart/retweets-lookup.md): Get users who Retweeted a Post - [Retweets of Me](https://docs.x.com/enterprise-api/posts/retweets/quickstart/retweets-of-me.md): Get your Posts that have been Retweeted -- [Manage Retweets](https://docs.x.com/enterprise-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST statuses/retweet/:id](https://developer. -- [Overview](https://docs.x.com/enterprise-api/posts/retweets/migrate/overview.md): **Retweets lookup** The v2 Retweets lookup endpoint will replace the standard [v1. 1 GET statuses/retweets/:id](https: -- [Retweets lookup](https://docs.x.com/enterprise-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. +- [Manage Retweets](https://docs.x.com/enterprise-api/posts/retweets/migrate/manage-retweets-standard-to-twitter-api-v2.md) +- [Overview](https://docs.x.com/enterprise-api/posts/retweets/migrate/overview.md) +- [Retweets lookup](https://docs.x.com/enterprise-api/posts/retweets/migrate/retweets-lookup-standard-to-twitter-api-v2.md) - [Likes](https://docs.x.com/enterprise-api/posts/likes/introduction.md): Like and unlike Posts, and retrieve like information - [Likes Lookup](https://docs.x.com/enterprise-api/posts/likes/quickstart/likes-lookup.md): Get users who liked a Post and Posts liked by a user - [Manage Likes](https://docs.x.com/enterprise-api/posts/likes/quickstart/manage-likes.md): Like and unlike Posts using the X API -- [Likes lookup](https://docs.x.com/enterprise-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET favorites/list](https://developer. -- [Manage Likes](https://docs.x.com/enterprise-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST favorites/create](https://developer. -- [Overview](https://docs.x.com/enterprise-api/posts/likes/migrate/overview.md): These guides will focus on the following areas: * **API request parameters** - The X API v2 endpoint introduces a new +- [Likes lookup](https://docs.x.com/enterprise-api/posts/likes/migrate/likes-lookup-standard-to-twitter-api-v2.md) +- [Manage Likes](https://docs.x.com/enterprise-api/posts/likes/migrate/manage-likes-standard-to-twitter-api-v2.md) +- [Overview](https://docs.x.com/enterprise-api/posts/likes/migrate/overview.md) - [Apps](https://docs.x.com/enterprise-api/posts/hide-replies/apps.md): Here's a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their - [Hide Replies](https://docs.x.com/enterprise-api/posts/hide-replies/introduction.md): Hide and unhide replies to Posts you authored -- [Migration guide](https://docs.x.com/enterprise-api/posts/hide-replies/migrate.md): The v2 hide replies endpoint is replacing the Labs hide replies endpoint. If you have code, apps, or tools that use th +- [Migration guide](https://docs.x.com/enterprise-api/posts/hide-replies/migrate.md) - [Quickstart](https://docs.x.com/enterprise-api/posts/hide-replies/quickstart.md): Hide and unhide replies to your Posts - [Manage replies by topic](https://docs.x.com/enterprise-api/posts/hide-replies/integrate/manage-replies-by-topic.md): Through the hide replies endpoint, you can build integrations to help people and brands keep their conversation on top - [Manage replies by topic](https://docs.x.com/enterprise-api/posts/hide-replies/integrate/manage-replies-in-realtime.md): With the hide replies endpoint, you can build a workflow to helps your users hide replies that have a very high-probab -- [Integration Guide](https://docs.x.com/enterprise-api/posts/lookup/integrate.md): Key concepts and best practices for integrating Post lookup +- [Integration Guide](https://docs.x.com/enterprise-api/posts/lookup/integrate.md) - [Post Lookup](https://docs.x.com/enterprise-api/posts/lookup/introduction.md): Retrieve Posts by ID to get details, verify availability, and examine edit history - [Quickstart](https://docs.x.com/enterprise-api/posts/lookup/quickstart.md): Make your first Post lookup request in minutes -- [Overview](https://docs.x.com/enterprise-api/posts/lookup/migrate/overview.md): The v2 Posts lookup endpoints replace the standard v1. 1 [GET statuses/lookup](https://developer. -- [v1 to v2](https://docs.x.com/enterprise-api/posts/lookup/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 GET statuses/show and GET statuses/lookup, this guide will help you u -- [Integration Guide](https://docs.x.com/enterprise-api/posts/timelines/integrate.md): Key concepts and best practices for integrating Timelines endpoints +- [Overview](https://docs.x.com/enterprise-api/posts/lookup/migrate/overview.md) +- [v1 to v2](https://docs.x.com/enterprise-api/posts/lookup/migrate/standard-to-twitter-api-v2.md) +- [Integration Guide](https://docs.x.com/enterprise-api/posts/timelines/integrate.md) - [Timelines](https://docs.x.com/enterprise-api/posts/timelines/introduction.md): Retrieve Posts from user timelines and home feeds - [Home Timeline Quickstart](https://docs.x.com/enterprise-api/posts/timelines/quickstart/reverse-chron-quickstart.md): Get a user's home timeline in reverse chronological order - [User Mentions Timeline](https://docs.x.com/enterprise-api/posts/timelines/quickstart/user-mention-quickstart.md): Get Posts that mention a specific user -- [Overview](https://docs.x.com/enterprise-api/posts/timelines/migrate/overview.md): The v2 reverse chronological timeline, user Posts timeline, and user mention timeline endpoints replace the [v1. 1 sta -- [v1 to v2](https://docs.x.com/enterprise-api/posts/timelines/migrate/standard-to-twitter-api-v2.md): If you have been working with the v1. 1 timelines endpoints (statuses/user\_timeline and statuses/mentions\_timeline), +- [Overview](https://docs.x.com/enterprise-api/posts/timelines/migrate/overview.md) +- [v1 to v2](https://docs.x.com/enterprise-api/posts/timelines/migrate/standard-to-twitter-api-v2.md) - [Search Posts](https://docs.x.com/enterprise-api/posts/search/introduction.md): Search for Posts by keyword, hashtag, user, and more with powerful query operators - [Build a query](https://docs.x.com/enterprise-api/posts/search/integrate/build-a-query.md): Learn how to build search queries using operators - [Search Operators](https://docs.x.com/enterprise-api/posts/search/integrate/operators.md): Complete list of operators for Search queries @@ -232,10 +232,10 @@ - [Pagination](https://docs.x.com/enterprise-api/posts/search/integrate/paginate.md): Search queries typically match on more Posts than can be returned in a single API response. When that happens, the dat - [Full-Archive Search Quickstart](https://docs.x.com/enterprise-api/posts/search/quickstart/full-archive-search.md): Search the complete Post archive back to 2006 - [Recent Search Quickstart](https://docs.x.com/enterprise-api/posts/search/quickstart/recent-search.md): Make your first recent search request in minutes -- [v1 to v2 (Enterprise)](https://docs.x.com/enterprise-api/posts/search/migrate/enterprise-to-twitter-api-v2.md): **Similarities** * Pagination * Timezone * Support for Post edit history and metadata. **Differences** * Endpoint URLs -- [Overview](https://docs.x.com/enterprise-api/posts/search/migrate/overview.md): The v2 Search Tweets endpoint will eventually replace the [standard v1. 1 search/posts](/x-api/posts/search/introducti -- [v1 to v2](https://docs.x.com/enterprise-api/posts/search/migrate/standard-to-twitter-api-v2.md): If you have been working with the v1. 1 [search/posts](/x-api/posts/search/introduction), the goal of this guide is to -- [Integration guide](https://docs.x.com/enterprise-api/posts/bookmarks/integrate.md): This page contains information on several tools and critical concepts that you should know as you integrate the manage +- [v1 to v2 (Enterprise)](https://docs.x.com/enterprise-api/posts/search/migrate/enterprise-to-twitter-api-v2.md) +- [Overview](https://docs.x.com/enterprise-api/posts/search/migrate/overview.md) +- [v1 to v2](https://docs.x.com/enterprise-api/posts/search/migrate/standard-to-twitter-api-v2.md) +- [Integration guide](https://docs.x.com/enterprise-api/posts/bookmarks/integrate.md) - [Bookmarks](https://docs.x.com/enterprise-api/posts/bookmarks/introduction.md): Save and manage bookmarked Posts for the authenticated user - [Bookmarks Lookup](https://docs.x.com/enterprise-api/posts/bookmarks/quickstart/bookmarks-lookup.md): Retrieve your bookmarked Posts - [Manage Bookmarks](https://docs.x.com/enterprise-api/posts/bookmarks/quickstart/manage-bookmarks.md): Add and remove bookmarks using the X API @@ -246,27 +246,27 @@ - [Build a rule](https://docs.x.com/enterprise-api/posts/filtered-stream/integrate/build-a-rule.md): Learn how to build filtered stream rules using operators - [Matching Posts to Rules](https://docs.x.com/enterprise-api/posts/filtered-stream/integrate/matching-returned-tweets.md): The filtered stream endpoint gives you the ability to have multiple rules in place through a single connection. Before - [Filtered Stream Operators](https://docs.x.com/enterprise-api/posts/filtered-stream/integrate/operators.md): Complete list of operators for Filtered Stream rules -- [Overview](https://docs.x.com/enterprise-api/posts/filtered-stream/migrate/overview.md): The v2 filtered stream endpoints group is replacing the [standard v1. 1 statuses/filter](https://developer. -- [v1 to v2 (Enterprise)](https://docs.x.com/enterprise-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.md): Use this migration guide to understand the similarities and differences between [PowerTrack API](/x-api/enterprise-gni -- [v1 to v2](https://docs.x.com/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.md): If you have been working with the v1. 1 [statuses/filter](https://developer. +- [Overview](https://docs.x.com/enterprise-api/posts/filtered-stream/migrate/overview.md) +- [v1 to v2 (Enterprise)](https://docs.x.com/enterprise-api/posts/filtered-stream/migrate/powertrack-api-migration-to-twitter-api-v2.md) +- [v1 to v2](https://docs.x.com/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.md) - [Post Counts](https://docs.x.com/enterprise-api/posts/counts/introduction.md): Get Post volume data for queries without retrieving the Posts themselves - [Build a query](https://docs.x.com/enterprise-api/posts/counts/integrate/build-a-query.md): **Query limitations! ** Your queries will be limited depending on which [access level](/x-api/getting-started/about-x- -- [Overview](https://docs.x.com/enterprise-api/posts/counts/integrate/overview.md): This page covers tools and key concepts for integrating the Post counts endpoints. +- [Overview](https://docs.x.com/enterprise-api/posts/counts/integrate/overview.md) - [Full-Archive Post Counts](https://docs.x.com/enterprise-api/posts/counts/quickstart/full-archive-tweet-counts.md): Get historical Post volume back to 2006 - [Recent Post Counts](https://docs.x.com/enterprise-api/posts/counts/quickstart/recent-tweet-counts.md): Get Post volume for the last 7 days -- [v1 to v2 (Enterprise)](https://docs.x.com/enterprise-api/posts/counts/migrate/enterprise-to-twitter-api-v2.md): **Similarities** * Granularity * Pagination * Timezone **Differences** * Endpoint URLs * App and Project requirement * -- [Overview](https://docs.x.com/enterprise-api/posts/counts/migrate/overview.md): The v2 Post counts endpoint will eventually replace the [enterprise Search API’s counts endpoint](/x-api/enterprise-gn -- [Integration guide](https://docs.x.com/enterprise-api/posts/manage-tweets/integrate.md): This page covers tools and key concepts for integrating the manage Posts endpoints into your system. +- [v1 to v2 (Enterprise)](https://docs.x.com/enterprise-api/posts/counts/migrate/enterprise-to-twitter-api-v2.md) +- [Overview](https://docs.x.com/enterprise-api/posts/counts/migrate/overview.md) +- [Integration guide](https://docs.x.com/enterprise-api/posts/manage-tweets/integrate.md) - [Manage Posts](https://docs.x.com/enterprise-api/posts/manage-tweets/introduction.md): Create and delete Posts on behalf of authenticated users - [Quickstart](https://docs.x.com/enterprise-api/posts/manage-tweets/quickstart.md): Create and delete Posts using the X API -- [Overview](https://docs.x.com/enterprise-api/posts/manage-tweets/migrate/overview.md): The v2 manage Posts endpoints will replace the standard v1. 1 [POST statuses/update](https://developer. -- [v1 to v2](https://docs.x.com/enterprise-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST statuses/update](https://developer. +- [Overview](https://docs.x.com/enterprise-api/posts/manage-tweets/migrate/overview.md) +- [v1 to v2](https://docs.x.com/enterprise-api/posts/manage-tweets/migrate/standard-to-twitter-api-v2.md) ## Powerstream -- [Handling disconnections](https://docs.x.com/enterprise-api/powerstream/handling-disconnections.md): This page covers Powerstream-specific disconnection handling. For comprehensive guidance on handling disconnections ac -- [Introduction](https://docs.x.com/enterprise-api/powerstream/introduction.md): Powerstream is our **lowest-latency streaming API** for accessing public X data in real-time. Unlike other streaming e +- [Handling disconnections](https://docs.x.com/enterprise-api/powerstream/handling-disconnections.md) +- [Introduction](https://docs.x.com/enterprise-api/powerstream/introduction.md) - [Powerstream Operators](https://docs.x.com/enterprise-api/powerstream/operators.md): Complete list of operators for Powerstream filtering rules -- [Recovery and redundancy](https://docs.x.com/enterprise-api/powerstream/recovery-and-redundancy.md): This page covers Powerstream-specific recovery and redundancy features. For comprehensive guidance on recovery and red +- [Recovery and redundancy](https://docs.x.com/enterprise-api/powerstream/recovery-and-redundancy.md) ## Spaces - [Get Space By Id](https://docs.x.com/enterprise-api/spaces/get-space-by-id.md): Reference documentation for the endpoint and related functionality. @@ -354,28 +354,28 @@ - [Unmute User](https://docs.x.com/enterprise-api/users/unmute-user.md): Reference documentation for the endpoint and related functionality. - [Unpin List](https://docs.x.com/enterprise-api/users/unpin-list.md): Reference documentation for the endpoint and related functionality. - [Unrepost Post](https://docs.x.com/enterprise-api/users/unrepost-post.md): Reference documentation for the endpoint and related functionality. -- [Integration Guide](https://docs.x.com/enterprise-api/users/blocks/integrate.md): Key concepts and best practices for integrating blocks endpoints +- [Integration Guide](https://docs.x.com/enterprise-api/users/blocks/integrate.md) - [Blocks](https://docs.x.com/enterprise-api/users/blocks/introduction.md): Block and unblock users, and retrieve blocked user lists -- [Migration guide](https://docs.x.com/enterprise-api/users/blocks/migrate.md): If you have been working with the standard v1. 1 [GET blocks/ids](https://developer. +- [Migration guide](https://docs.x.com/enterprise-api/users/blocks/migrate.md) - [Quickstart](https://docs.x.com/enterprise-api/users/blocks/quickstart.md): Block and unblock users, and retrieve your block list -- [Integration Guide](https://docs.x.com/enterprise-api/users/mutes/integrate.md): Key concepts and best practices for integrating mutes endpoints +- [Integration Guide](https://docs.x.com/enterprise-api/users/mutes/integrate.md) - [Mutes](https://docs.x.com/enterprise-api/users/mutes/introduction.md): Mute and unmute users, and retrieve muted user lists - [Manage Mutes](https://docs.x.com/enterprise-api/users/mutes/quickstart/manage-mutes-quickstart.md): Mute and unmute users using the X API - [Mutes Lookup](https://docs.x.com/enterprise-api/users/mutes/quickstart/mutes-lookup.md): Get the list of users you have muted -- [Manage mutes](https://docs.x.com/enterprise-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST mutes/users/create](https://developer. -- [Mutes lookup](https://docs.x.com/enterprise-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [GET mutes/users/ids](https://developer. -- [Overview](https://docs.x.com/enterprise-api/users/mutes/migrate/overview.md): The v2 mutes lookup endpoint will replace the standard [v1. 1 GET mutes/users/ids](https://developer. -- [Integration Guide](https://docs.x.com/enterprise-api/users/lookup/integrate.md): Key concepts and best practices for integrating User lookup +- [Manage mutes](https://docs.x.com/enterprise-api/users/mutes/migrate/manage-mutes-standard-to-twitter-api-v2.md) +- [Mutes lookup](https://docs.x.com/enterprise-api/users/mutes/migrate/mutes-lookup-standard-to-twitter-api-v2.md) +- [Overview](https://docs.x.com/enterprise-api/users/mutes/migrate/overview.md) +- [Integration Guide](https://docs.x.com/enterprise-api/users/lookup/integrate.md) - [User Lookup](https://docs.x.com/enterprise-api/users/lookup/introduction.md): Retrieve user profiles by ID, username, or for the authenticated user - [Authenticated User Quickstart](https://docs.x.com/enterprise-api/users/lookup/quickstart/authenticated-lookup.md): Get the currently authenticated user's profile - [User Lookup Quickstart](https://docs.x.com/enterprise-api/users/lookup/quickstart/user-lookup.md): Look up users by ID or username -- [Overview](https://docs.x.com/enterprise-api/users/lookup/migrate/overview.md): The v2 user lookup endpoints will replace the standard v1. 1 [GET users/lookup](https://developer. -- [v1 to v2](https://docs.x.com/enterprise-api/users/lookup/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 GET users/show and GET users/lookup, the goal of this guide is to hel +- [Overview](https://docs.x.com/enterprise-api/users/lookup/migrate/overview.md) +- [v1 to v2](https://docs.x.com/enterprise-api/users/lookup/migrate/standard-to-twitter-api-v2.md) - [User Search](https://docs.x.com/enterprise-api/users/search/introduction.md): Search for users by keyword - [Follows](https://docs.x.com/enterprise-api/users/follows/introduction.md): Manage follows and retrieve follower/following information - [Quickstart](https://docs.x.com/enterprise-api/users/follows/quickstart.md): Get followers and following lists, and manage follows -- [Overview](https://docs.x.com/enterprise-api/users/follows/migrate/overview.md): The v2 follows lookup endpoints will replace the standard v1. 1 [followers/ids](https://developer. -- [v1 to v2](https://docs.x.com/enterprise-api/users/follows/migrate/standard-to-twitter-api-v2.md): If you have been working with the standard v1. 1 [POST friendships/create](https://developer. +- [Overview](https://docs.x.com/enterprise-api/users/follows/migrate/overview.md) +- [v1 to v2](https://docs.x.com/enterprise-api/users/follows/migrate/standard-to-twitter-api-v2.md) ## Webhooks - [Create Replay Job For Webhook](https://docs.x.com/enterprise-api/webhooks/create-replay-job-for-webhook.md): Reference documentation for the endpoint and related functionality. @@ -391,5 +391,6 @@ - [Filtered Stream Webhooks API](https://docs.x.com/enterprise-api/webhooks/stream/introduction.md): The filtered stream endpoint group enables developers to filter a stream of public Posts. This endpoint group’s functi - [Quickstart](https://docs.x.com/enterprise-api/webhooks/stream/quickstart.md): The v2 filtered stream webhooks API is similar to the [v2 filtered stream endpoint](/x-api/posts/filtered-stream/intro -## Full Documentation +## Agent Resources +- [AGENTS.md](https://docs.x.com/AGENTS.md) - [llms-full.txt](https://docs.x.com/llms-full.txt) \ No newline at end of file diff --git a/enterprise-api/media/introduction.mdx b/enterprise-api/media/introduction.mdx index d23954962..f6561c5a8 100644 --- a/enterprise-api/media/introduction.mdx +++ b/enterprise-api/media/introduction.mdx @@ -28,4 +28,4 @@ An entity which contains media object(s) can be created by following these steps ## Retrieving -Please refer to the [Media Object](/x-api/fundamentals/data-dictionary#media) in the data dictionary. \ No newline at end of file +Please refer to the [Media Object](/x-api/fundamentals/data-dictionary/reference#media) in the data dictionary. \ No newline at end of file diff --git a/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx b/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx index 33db29d59..780f55f56 100644 --- a/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx +++ b/enterprise-api/posts/filtered-stream/migrate/standard-to-twitter-api-v2.mdx @@ -75,12 +75,12 @@ For the standard endpoints, you receive many of the response fields by default, The X API v2 version only delivers the Post id and text fields by default. To request any additional fields or objects, you wil need to use the [fields](/x-api/fundamentals/fields) and [expansions](/x-api/fundamentals/expansions) parameters. Any Post fields that you request from these endpoints will return in the primary Post object. Any expanded user, media, poll, or place objects and fields will return in an includes object within your response. You can then match any expanded objects back to the Post object by matching the IDs located in both the Post and the expanded object.  -We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).  +We encourage you to read more about these new parameters in their respective guides, or by reading our guide on [how to use fields and expansions](/x-api/fundamentals/data-dictionary/reference#how-to-use-fields-and-expansions).  We have also put together a [data format migration guide](/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2) which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.    -In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and [user](/x-api/fundamentals/data-dictionary#user) objects. +In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and [user](/x-api/fundamentals/data-dictionary/reference#user) objects. * At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.  * Instead of referring to Retweeted and Quoted "statuses", X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.  @@ -88,7 +88,7 @@ In addition to the changes in how you request certain fields, X API v2 is also * X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.    -We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary#tweet) including the following: +We also introduced a new set of fields to the [Post object](/x-api/fundamentals/data-dictionary/reference#tweet) including the following: * A [conversation_id](/x-api/fundamentals/conversation-id) field * Two new [annotations](/x-api/fundamentals/post-annotations) fields, including context and entities diff --git a/enterprise-api/posts/retweets/integrate.mdx b/enterprise-api/posts/retweets/integrate.mdx index cd00ea407..63e1ee18d 100644 --- a/enterprise-api/posts/retweets/integrate.mdx +++ b/enterprise-api/posts/retweets/integrate.mdx @@ -74,7 +74,7 @@ The X API v2 allows users to select exactly which data they want to return from The fields parameter allows you to select exactly which [fields](/x-api/fundamentals/fields) within the different data objects you would like to receive. These endpoints delivers Post objects primarily. By default, the Post object returns the id and text fields. To receive additional fields such as tweet.created_at or tweet.entities, you will have to specifically request those using a fields parameter. Some important fields that you may want to consider using in your integration are our poll data, metrics, Post annotations, and conversation ID fields. -We've added a guide on how to [use fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). +We've added a guide on how to [use fields and expansions](/x-api/fundamentals/data-dictionary/reference#how-to-use-fields-and-expansions) together to our [X API v2 data dictionary](/x-api/fundamentals/data-dictionary). --- diff --git a/enterprise-api/posts/volume-streams/introduction.mdx b/enterprise-api/posts/volume-streams/introduction.mdx index 1cb108ee2..65cda57dd 100644 --- a/enterprise-api/posts/volume-streams/introduction.mdx +++ b/enterprise-api/posts/volume-streams/introduction.mdx @@ -11,7 +11,7 @@ import { Button } from '/snippets/button.mdx'; These are referred to as "volume streams" because they both deliver large volumes of data. Even the 1% stream can emit many dozens of Posts every second. With these streams, you can identify and track trends, monitor general sentiment, monitor global events, and much more.  -These streaming endpoints deliver [Post objects](/x-api/fundamentals/data-dictionary#tweet) through a persistent HTTP GET connection and use [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) authentication. With Essential access, you can have one connection at a time. With all levels of access, connection requests can be made up to 50 times per 15-minute window. +These streaming endpoints deliver [Post objects](/x-api/fundamentals/data-dictionary/reference#tweet) through a persistent HTTP GET connection and use [OAuth 2.0 App-Only](/resources/fundamentals/authentication#oauth-2-0) authentication. With Essential access, you can have one connection at a time. With all levels of access, connection requests can be made up to 50 times per 15-minute window. These volume stream endpoints support edited Posts. These endpoints will deliver edited Posts, along with its edit history, including an array of Post IDs. For Posts with no edit history, this array will hold a single ID. For Posts that have been edited, this array contains multiple IDs, arranged in ascending order reflecting the order of edits, with the most recent version in the last position of the array. To learn more about how Post edits work, see the [Post edits fundamentals](/x-api/fundamentals/edit-posts) page.  diff --git a/enterprise-api/spaces/introduction.mdx b/enterprise-api/spaces/introduction.mdx index 9c605f935..1921d2041 100644 --- a/enterprise-api/spaces/introduction.mdx +++ b/enterprise-api/spaces/introduction.mdx @@ -19,7 +19,7 @@ We encourage you to use your creativity to extend Spaces beyond the way we built The following resources will help you get started and integrate with the Spaces endpoints: * [Getting access to X API v2](/x-api/getting-started/getting-access) -* [Spaces data dictionary](/x-api/fundamentals/data-dictionary#space) +* [Spaces data dictionary](/x-api/fundamentals/data-dictionary/reference#space) * [Make your first request to a Spaces endpoint](/x-api/spaces/lookup/introduction)   @@ -50,7 +50,7 @@ These endpoints reflect the way Spaces work on the X app. In Spaces, X users can ### Creator (or primary host) -The primary Host is the user who created a Space, and the owner of the Space itself. Currently, Spaces can only have one Host, so the primary Host will be the only Host. In the [Spaces data dictionary](/x-api/fundamentals/data-dictionary#space), the primary Host information will be in the creator_id field, which can be expanded into a [user object](/x-api/fundamentals/data-dictionary#user). +The primary Host is the user who created a Space, and the owner of the Space itself. Currently, Spaces can only have one Host, so the primary Host will be the only Host. In the [Spaces data dictionary](/x-api/fundamentals/data-dictionary/reference#space), the primary Host information will be in the creator_id field, which can be expanded into a [user object](/x-api/fundamentals/data-dictionary/reference#user).   ### Hosts diff --git a/enterprise-api/webhooks/stream/introduction.mdx b/enterprise-api/webhooks/stream/introduction.mdx index 72ec3bf6d..6004990cd 100644 --- a/enterprise-api/webhooks/stream/introduction.mdx +++ b/enterprise-api/webhooks/stream/introduction.mdx @@ -13,7 +13,7 @@ The filtered stream endpoint group enables developers to filter a stream of publ Developers can use the REST [rules endpoint](/x-api/stream/get-stream-rules) to add and remove rules to filter for Posts matching a defined criteria. These [rules](/x-api/posts/filtered-stream/integrate/build-a-rule) can be created with operators that match on Post attributes such as message keywords, hashtags, and URLs. Operators and rule clauses can be combined with boolean logic and parentheses to help refine the filter’s matching behavior.  -Once you've added a set of rules, you can register your webhook where X will start to deliver [Post objects](/x-api/fundamentals/data-dictionary#tweet) in JSON format. You will only receive content matching your rules to your webhook. +Once you've added a set of rules, you can register your webhook where X will start to deliver [Post objects](/x-api/fundamentals/data-dictionary/reference#tweet) in JSON format. You will only receive content matching your rules to your webhook. This endpoint supports edited Posts. Your webhook will receive edited Posts that match one or more of your filters, along with its edit history, including an array of Post IDs. For Posts with no edit history, this array will hold a single ID. For Posts that have been edited, this array contains multiple IDs, arranged in ascending order reflecting the order of edits, with the most recent version in the last position of the array. To learn more about how Post edits work, see the [Posts edits fundamentals](/x-api/fundamentals/edit-posts) page.  diff --git a/tutorials/explore-a-users-posts.mdx b/tutorials/explore-a-users-posts.mdx index 6790e4a68..fbfcb7022 100644 --- a/tutorials/explore-a-users-posts.mdx +++ b/tutorials/explore-a-users-posts.mdx @@ -90,7 +90,7 @@ You will see that the JSON response for these requests contains the ID and text } ``` -If you want additional fields returned as part of the response (such as user information, additional Tweet fields such as context annotations etc.) then you will need to specify those fields explicitly in your response. Learn how to do this from the [guide on using fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions). +If you want additional fields returned as part of the response (such as user information, additional Tweet fields such as context annotations etc.) then you will need to specify those fields explicitly in your response. Learn how to do this from the [guide on using fields and expansions](/x-api/fundamentals/data-dictionary/reference#how-to-use-fields-and-expansions). You can also get these Posts using programming languages of your choice. Check out our sample code in Python, Node (JavaScript), Java and Ruby for the user Tweet timeline and user mention timeline endpoints on our [Github repository](https://github.com/xdevplatform/Twitter-API-v2-sample-code).   diff --git a/tutorials/getting-started-with-r-and-v2-of-the-x-api.mdx b/tutorials/getting-started-with-r-and-v2-of-the-x-api.mdx index 5d3ead0d1..6fdea512a 100644 --- a/tutorials/getting-started-with-r-and-v2-of-the-x-api.mdx +++ b/tutorials/getting-started-with-r-and-v2-of-the-x-api.mdx @@ -17,7 +17,7 @@ If you aren't familiar, R is one of the most popular languages for common Data Science tasks like time-series analysis, modeling, visualization, and other data analysis, and is often used in conjunction with the X API. With the user lookup endpoint, you can use the -[user object](/x-api/fundamentals/data-dictionary#user) to +[user object](/x-api/fundamentals/data-dictionary/reference#user) to determine a correlation between the number of followers a person has and the sentiment score of their bio. The user object may also be used to map a group of accounts based on the location publicly listed in their profiles. diff --git a/x-ads-api/audiences.mdx b/x-ads-api/audiences.mdx index f73aca511..7c9bea70d 100644 --- a/x-ads-api/audiences.mdx +++ b/x-ads-api/audiences.mdx @@ -1,9 +1,18 @@ --- title: Audiences -description: Create and manage Tailored Audiences and Custom Audiences using CRM lists, website visitors, mobile app users, or engagement data for precise ad targeting. -keywords: ["custom audiences", "tailored audiences", "audience targeting", "audience management", "ad targeting", "audience API"] +sidebarTitle: Overview +description: Create and manage Tailored Audiences and Custom Audiences using CRM data, website visitors, mobile app users, and engagement signals for precise targeting in X advertising campaigns. +keywords: ["audiences", "tailored audiences", "custom audiences", "audience targeting", "crm audiences", "web audiences", "audience api", "x ads audiences"] --- -import { Button } from '/snippets/button.mdx'; + +import { Button } from "/snippets/button.mdx"; + +**Build highly targeted audiences for your X ad campaigns using first-party data and X engagement signals.** + +## Quick Links + +- [Full API Reference](/x-ads-api/audiences/reference) — All Audience endpoints and objects +- [Guides](#guides) — CRM, Web, Mobile, ID Sync, User Data uploads, FAQ ## Custom Audiences @@ -305,7 +314,7 @@ Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d98 Partners sending data with a `p_id` must undergo an ID Sync process to generate a mapping of the advertiser or partner’s user ids to X user ids. This allows advertisers to directly target their own user segments on X. Partners must also set the value of the param `user_identifier_type` to either `TALIST_PARTNER_USER_ID` or `TAWEB_PARTNER_USER_ID` while sending their membership updates. * **Web Only**: This can be done by placing a pixel on the advertiser’s site, as outlined below. -* **List**: This can be done using any of the methods described on the [CRM](/x-ads-api/audiences#crm) page. +* **List**: This can be done using any of the methods described on the [CRM](/x-ads-api/audiences/reference#crm) page. #### Pixel URL @@ -605,1333 +614,19 @@ With the deprecation of the global opt-out endpoint, partners are required to `D * This endpoint is atomic in nature, that is, either the entire request is successful or in case of any errors then the entire request will fail. In case of an error response, consumers of the API are recommended to fix the error and retry the request with the entire payload.  * Upon failure, partners recommended to use an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) approach with retries. For example, retry immediately upon the first failure, retry after 1 minute after the second failure and retry after 5 minutes after the third consecutive failure, and so on +--- -## API Reference - -### Keyword Insights - - -#### GET insights/keywords/search[](#get-insights-keywords-search "Permalink to this headline") - -Given a group of keywords, get the associated Tweet volume as well as a set of 30 related keywords. The Tweet volume corresponds to the input keywords only, not the related keywords. - -A maximum time range (`end_time` \- `start_time`) of 7 days is allowed. - -Please note that results are scoped by a single geo (country). - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/insights/keywords/search` - -**Parameters[](#parameters "Permalink to this headline")** - -| Name | Description | -| :--- | :--- | -| granularity
_required_ | Specifies the granularity of the data returned for the time range denoted by `start_time` and `end_time`. For instance, when set to `HOUR`, you will be presented with a datapoint for each hour between `start_time` and `end_time`. request.

Type: enum

Possible values: `DAY`, `HOUR` | -| keywords
_required_ | A comma-separated string of keywords to narrow search by. All keywords are OR'ed with one another.

**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.

Type: string

Example: `developers` | -| start_time
_required_ | Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

Type: string

Example: `2017-07-10T00:00:00Z` | -| end_time
_optional_ | Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Defaults to the current time.

Type: string

Example: `2017-07-11T00:00:00Z` | -| location
_optional_ | A targeting value you would get from the [GET targeting_criteria/locations](/x-ads-api/campaign-management/reference#get-targeting-criteria-locations) endpoint to narrow results in terms of where the user of the account is located. Note that at present only country level locations are supported.

Type: string

Example: `0ce8b9a7b2742f7e` | -| negative_keywords
_optional_ | A comma-separated string of keywords to exclude. All negative keywords are OR'ed with one another.

**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.

Type: string

Example: `rain` | - -**Example Request[](#example-request "Permalink to this headline")** - -```json -GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01 -``` - -**Example Response[](#example-response "Permalink to this headline")*** -``` - { - "request": { - "params": { - "start_time": "2018-02-01T00:00:00Z", - "end_time": "2018-02-02T00:00:00Z", - "granularity": "DAY", - "keywords": [ - "developers" - ] - } - }, - "data": { - "related_keywords": [ - "dev", - "developer", - "coders", - "mysql", - "devs", - "#technology", - "#developers", - "security", - "programmers", - "#tech", - "javascript", - "#iot", - "#bigdata", - "cloud", - "devops", - "php", - "developer", - "programmer", - "engineer", - "big data", - "agile", - "app", - "programming", - "ios", - "maker", - "startups", - "developer's", - "java", - "#devops", - "startup" - ], - "tweet_volume": [ - 15707 - ] - } - } -``` - -### Tailored Audience Permissions - - - -#### GET accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#get-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline") - -Retrieve details for some or all permissions associated with the specified tailored audience. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| tailored\_audience\_id
_required_ | A reference to the tailored audience you are operating with in the request.

Type: string

Example: `1nmth` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| granted\_account\_ids
_optional_ | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `18ce54aymz3` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.

Type: string

Example: `created_at-asc` | -| tailored\_audience\_permission_ids
_optional_ | Scope the response to just the desired tailored audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `ri` | -| 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "tailored_audience_id": "1nmth" - } - }, - "next_cursor": null, - "data": [ - { - "tailored_audience_id": "1nmth", - "permission_level": "READ_ONLY", - "id": "ri", - "created_at": "2017-06-08T23:17:59Z", - "granted_account_id": "18ce54aymz3", - "updated_at": "2017-06-08T23:17:59Z", - "deleted": false - } - ] - } - -``` -#### POST accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#post-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline") - -Create a new permission object allowing the specified audience to be shared with a given account. - -**Note**: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the `is_owner` response attribute in the response for a given audience. - -**Note**: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the `SHARE_AUDIENCE_OUTSIDE_BUSINESS` account feature. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| granted\_account\_id
_required_ | The account you wish to grant the tailored audience permissions for.

Type: string

Example: `18ce54aymz3` | -| permission_level
_required_ | The type of access to the tailored audience that the `granted_account_id` should have.

Type: enum

Possible values: `READ_ONLY`, `READ_WRITE` | -| tailored\_audience\_id
_required_ | A reference to the tailored audience you are operating with in the request.

Type: string

Example: `2906h` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "granted_account_id": "18ce54aymz3", - "permission_level": "READ_ONLY", - "tailored_audience_id": "2906h" - } - }, - "data": { - "tailored_audience_id": "2906h", - "permission_level": "READ_ONLY", - "id": "14m", - "created_at": "2017-09-12T23:49:34Z", - "granted_account_id": "18ce54aymz3", - "updated_at": "2017-09-12T23:49:34Z", - "deleted": false - } - } -``` - -#### DELETE accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions/:tailored\_audience\_permission_id[](#delete-accounts-account-id-tailored-audiences-tailored-audience-id-permissions-tailored-audience-permission-id "Permalink to this headline") - -Revoke the specified Tailored Audience sharing permission. - -**Note**: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the `is_owner` response attribute in the response for a given audience. - -When revoked, we guarantee that the granted account (`granted_account_id`) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| tailored\_audience\_id
_required_ | A reference to the tailored audience you are operating with in the request.

Type: string

Example: `1nmth` | -| tailored\_audience\_permission_id
_required_ | A reference to the tailored audience permission you are operating with in the request.

Type: string

Example: `ri` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "tailored_audience_permission_id": "ri", - "tailored_audience_id": "1nmth" - } - }, - "data": { - "tailored_audience_id": "1nmth", - "permission_level": "READ_ONLY", - "id": "ri", - "created_at": "2017-06-08T23:17:59Z", - "granted_account_id": "18ce54aymz3", - "updated_at": "2017-08-30T18:29:35Z", - "deleted": true - } - } -``` - -### Targeted Audiences - -#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/targeted[](#get-accounts-account-id-custom-audiences-custom-audience-id-targeted "Permalink to this headline") - -Retrieve a list of active or all line items and campaigns that target a given `custom_audience_id` - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | -| with_active
_optional_ | When `false`, includes line items that have `servable=false` status

Type: boolean

Default: `true`
Possible values: `true`, `false` | -| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "custom_audience_id": "2906h", - } - }, - "next_cursor": null, - "data": [ - { - "campaign_id": "59hod", - "campaign_name": "test-campaign", - "line_items": [ - { - "id": "5gzog", - "name": "test-line-item", - "servable": true - } - ] - }, - { - "campaign_id": "arja7", - "campaign_name": "Untitled campaign", - "line_items": [ - { - "id": "bjw1q", - "name": null, - "servable": true - } - ] - } - ] - } -``` - -### Custom Audiences Users - - -#### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users[](#post-accounts-account-id-custom-audiences-custom-audience-id-users "Permalink to this headline") - -This endpoint will allow partners to add, update and remove users from a given `custom_audience_id`. The endpoint will also accept multiple user identifier types per user as well. - -All data being provided in the `users` field of the request **except** `partner_user_id` must be hashed using `SHA256` and [normalized](/x-ads-api/audiences#twitter-user-id-normalization). - -**Batch Requests** - -* The current maximum batch size is `2500` **for this endpoint**. The batch size is determined by the number of operations (`Update`/`Delete`) per request. For example, over 2500 operation objects (`{"operation_type": "Update/Delete", [..] }`) in one array result in an error. -* The max request POST body size this endpoint can accept is `5,000,000` bytes. -* The rate limits for this endpoint are 1500 per 1 minute window -* 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** - -The response returned by the Ads API contains two fields, a `success_count` and a `total_count`. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is **not** equal the `success_count` and `total_count` should be treated as an error condition, requiring a retry. - -**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 parameters) are show in the response under the `operation_errors` object. -* The index of the error in the `operation_errors` refers to the index in the input item, with the corresponding error message - -#### Resource URL[](#resource-url "Permalink to this headline") - -`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users` - -#### Parameters[](#parameters "Permalink to this headline") - -| Name | Description | -| :--- | :--- | -| operation_type
_required_ | The per `users` group operation type being performed.

Type: enum

Possible values: `Update`, `Delete` | -| params
_required_ | A JSON object containing the `users` array, the `effective_at` and `expires_at` timestamps.

Type: JSON | -| users
_required_ | An array of JSON objects containing all params for an individual user.

Type: JSON | -| effective_at
_optional_ | The UTC time at which the custom audience association(s) should take effect. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to the current date and time.

Type: string

Example: `2017-07-05T07:00:00Z` | -| expires_at
_optional_ | The UTC time at which the custom audience association(s) should expire. The specified time must be later than the value of `effective_at`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to 13 months from the request timestamp.

Type: string

Example: `2017-07-05T07:00:00Z` | - -Given the mutil-key approach to the `users` object, each element of this object is documented below: - -| Name | Description | -| :--- | :--- | -| email
_optional_ | Email address(es) for the user.

Type: Array\[String\] | -| device_id
_optional_ | IDFA/AdID/Android ID

Type: Array\[String\] | -| handle
_optional_ | The @handle(s) belonging to the user

Type: Array\[String\] | -| twitter_id
_optional_ | The X ID belonging to the user

Type: Array\[String\] | -| phone_number
_optional_ | Phone number(s) for the user

Type: Array\[String\] | -| partner\_user\_id
_optional_ | The user's ID in the partners' system.

Type: Array\[String\] | - -#### Example Request[](#example-request "Permalink to this headline") - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users` -``` - [ - { - "operation_type": "Update", - "params": { - "effective_at": "2018-05-15T00:00:00Z", - "expires_at": "2019-01-01T07:00:00Z", - "users": [ - { - "email": [ - "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3" - ], - "handle": [ - "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb", - "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d" - ] - }, - { - "email": [ - "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c" - ], - "twitter_id": [ - "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf", - "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85" - ] - } - ] - } - }, - { - "operation_type": "Delete", - "params": { - "effective_at": "2018-05-15T00:00:00Z", - "expires_at": "2019-01-01T07:00:00Z", - "users": [ - { - "device_id": [ - "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92" - ], - "email": [ - "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3" - ], - "handle": [ - "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847" - ], - "twitter_id": [ - "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b" - ] - }, - { - "email": [ - "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c" - ], - "twitter_id": [ - "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5", - "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8" - ] - } - ] - } - } - ] -``` -#### Example Response[](#example-response "Permalink to this headline") -``` - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "custom_audience_id": "1nmth" - } - }, - "data": { - "success_count": 4, - "total_count": 4 - } - } -``` - -### Custom Audience Permissions - - - -#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#get-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline") - -Retrieve details for some or all permissions associated with the specified custom audience. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `1nmth` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| granted\_account\_ids
_optional_ | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `18ce54aymz3` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.

Type: string

Example: `created_at-asc` | -| custom\_audience\_permission_ids
_optional_ | Scope the response to just the desired custom audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `ri` | -| 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "custom_audience_id": "1nmth" - } - }, - "next_cursor": null, - "data": [ - { - "custom_audience_id": "1nmth", - "permission_level": "READ_ONLY", - "id": "ri", - "created_at": "2017-06-08T23:17:59Z", - "granted_account_id": "18ce54aymz3", - "updated_at": "2017-06-08T23:17:59Z", - "deleted": false - } - ] - } -``` -#### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#post-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline") - -Create a new permission object allowing the specified audience to be shared with a given account. - -**Note**: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the `is_owner` response attribute in the response for a given audience. - -**Note**: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the `SHARE_AUDIENCE_OUTSIDE_BUSINESS` account feature. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| granted\_account\_id
_required_ | The account you wish to grant the custom audience permissions for.

Type: string

Example: `18ce54aymz3` | -| permission_level
_required_ | The type of access to the custom audience that the `granted_account_id` should have.

Type: enum

Possible values: `READ_ONLY`, `READ_WRITE` | -| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | - -**Example Request[](#example-request "Permalink to this headline")** - -``` -POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY -``` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "granted_account_id": "18ce54aymz3", - "permission_level": "READ_ONLY", - "custom_audience_id": "2906h" - } - }, - "data": { - "custom_audience_id": "2906h", - "permission_level": "READ_ONLY", - "id": "14m", - "created_at": "2017-09-12T23:49:34Z", - "granted_account_id": "18ce54aymz3", - "updated_at": "2017-09-12T23:49:34Z", - "deleted": false - } - } -``` -#### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions/:custom\_audience\_permission_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id-permissions-custom-audience-permission-id "Permalink to this headline") - -Revoke the specified Custom Audience sharing permission. - -**Note**: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the `is_owner` response attribute in the response for a given audience. - -When revoked, we guarantee that the granted account (`granted_account_id`) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `1nmth` | -| custom\_audience\_permission_id
_required_ | A reference to the custom audience permission you are operating with in the request.

Type: string

Example: `ri` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "account_id": "18ce54d4x5t", - "custom_audience_permission_id": "ri", - "custom_audience_id": "1nmth" - } - }, - "data": { - "custom_audience_id": "1nmth", - "permission_level": "READ_ONLY", - "id": "ri", - "created_at": "2017-06-08T23:17:59Z", - "granted_account_id": "18ce54aymz3", - "updated_at": "2017-08-30T18:29:35Z", - "deleted": true - } - } -``` - -### Custom Audiences - - -#### GET accounts/:account\_id/custom\_audiences[](#get-accounts-account-id-custom-audiences "Permalink to this headline") - -Retrieve details for some or all Custom Audiences associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/custom_audiences` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | -| permission_scope
_optional_ | Allows filtering the response to lists you own or lists that have been shared with you. By default, without specifying this parameter you will only see audiences you own.

Type: enum

Default: `OWNER`
Possible values: `OWNER`, `SHARED` | -| q
_optional_ | An optional query to scope resource by `name`.

**Note**: This performs case-insensitive prefix matching.

Type: string

Min, Max length: `1`, `255` | -| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.

Type: string

Example: `created_at-asc` | -| custom\_audience\_ids
_optional_ | Scope the response to just the desired custom audiences by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `1nmth` | -| 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 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[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "custom_audience_ids": [ - "1nmth" - ], - "account_id": "18ce54d4x5t" - } - }, - "next_cursor": null, - "data": [ - { - "targetable": true, - "name": "twurl-using-subshell-for-file", - "targetable_types": [ - "CRM", - "EXCLUDED_CRM" - ], - "audience_type": "CRM", - "description": null, - "permission_level": "READ_WRITE", - "owner_account_id": "18ce54d4x5t", - "id": "1nmth", - "reasons_not_targetable": [], - "created_at": "2017-01-08T08:19:58Z", - "updated_at": "2017-01-08T16:21:13Z", - "partner_source": "OTHER", - "deleted": false, - "audience_size": 1470 - } - ] - } -``` -#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#get-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline") - -Retrieve specific Custom Audiences associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "custom_audience_id": "2906h", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "targetable": false, - "name": "developers", - "targetable_types": [ - "CRM", - "EXCLUDED_CRM" - ], - "audience_type": "CRM", - "description": null, - "permission_level": "READ_WRITE", - "owner_account_id": "18ce54d4x5t", - "id": "2906h", - "reasons_not_targetable": [], - "created_at": "2017-08-22T23:34:26Z", - "updated_at": "2017-08-22T23:34:26Z", - "partner_source": "OTHER", - "deleted": false, - "audience_size": 140321 - } - } -``` -#### POST accounts/:account\_id/custom\_audiences[](#post-accounts-account-id-custom-audiences "Permalink to this headline") - -Create a new placeholder Custom Audience associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/custom_audiences` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| name
_required_ | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.

Type: string

Example: `ads api users` | -| description
_optional_ | A description for this audience.

Type: string

Example: `Collection of all users of the Ads API` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "data": { - "targetable": false, - "name": "developers", - "targetable_types": [ - "CRM", - "EXCLUDED_CRM" - ], - "audience_type": "CRM", - "description": null, - "permission_level": "READ_WRITE", - "owner_account_id": "18ce54d4x5t", - "id": "2906h", - "reasons_not_targetable": [ - "PROCESSING", - "TOO_SMALL" - ], - "created_at": "2017-08-22T23:34:26Z", - "updated_at": "2017-08-22T23:34:26Z", - "partner_source": "OTHER", - "deleted": false, - "audience_size": null - }, - "request": { - "params": { - "account_id": "18ce54d4x5t", - "name": "developers" - } - } - } -``` -#### PUT accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#put-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline") - -Update the specfic Custom Audience associated with the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| custom\_audience\_id
_required_ | A reference to the Custom Audience you are operating with in the request

Type: string

Example: `2906h` | -| name
_optional_ | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.

Type: string

Example: `ads api users` | -| description
_optional_ | A description for this audience.

Type: string

Example: `Collection of all users of the Ads API` | - -**Example Request[](#example-request "Permalink to this headline")** - -`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "data": { - "targetable": false, - "name": "developers_changed", - "targetable_types": [ - "CRM", - "EXCLUDED_CRM" - ], - "audience_type": "CRM", - "description": null, - "permission_level": "READ_WRITE", - "is_owner": true, - "id": "2906h", - "reasons_not_targetable": [ - "PROCESSING", - "TOO_SMALL" - ], - "created_at": "2017-08-22T23:34:26Z", - "updated_at": "2017-08-22T23:34:26Z", - "partner_source": "OTHER", - "deleted": false, - "audience_size": null - }, - "request": { - "params": { - "account_id": "18ce54d4x5t", - "name": "developers_changed" - } - } - } -``` -#### POST batch/accounts/:account\_id/custom\_audiences[](#post-batch-accounts-account-id-custom-audiences "Permalink to this headline") - -Allows for batch creation of Custom Audiences. See the [Custom Audiences Overview](/x-ads-api/audiences) page for information on audiences. - -**Note:** This batch endpoint is currently in **closed beta** and available to select advertisers. During this beta period, only Flexible Audiences based on mobile custom audiences can be created. - -**Batch Requests** - -* The current maximum batch size is 10. -* 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 parameter) are shown in the response under the `operation_errors` object. - -**Flexible Audiences** - - -* Flexible Audiences are immutable once created. -* Custom Audiences are passed in a tree structure with boolean logic combinations to create Flexible Audiences -* A maximum of 10 Custom Audiences leaf nodes can be used to create a Flexible Audience. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| audience_type
_required_ | The type of audience to create.

Type: enum

Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE` | -| child_segments
_required_ | An array containing objects which define the subset of a Custom Audience's members that you would like to target. Each object should contain a `custom_audience_id`, `frequency`, `frequency_comparator`, `lookback_window`, `negate`, and, in some cases, additional `child_segments`.

Type: array | -| name
_required_ | The display name for the audience. Unique name value must be used. Failure to do so will result in an error.

Type: string

Example: `my_flexible_audience_name` | -| operation_type
_required_ | The per item operation type being performed.

Type: enum

Possible values: `Create`, `Update`, `Delete` | -| boolean_operator
_sometimes required_ | The logical relationship between the child segments in its parent (containing) object. Required if child_segments is non-empty for the parent object.

Type: enum

Possible values: `AND`, `OR` | -| lookback_window
_sometimes required_ | An integer value specifying the range of days within which the user has taken the specific action and qualified for the given custom audience.

Type: int

Possible values: `1`, `7`, `14`, `30` | -| segments
_sometimes required_ | An object containing a `boolean_operator` and `child_segments` which define the subset of a Custom Audience's members that you would like to target.

Type: object | -| custom\_audience\_id
_sometimes required_ | The id of the custom audience to use as a child segment.

Type: string

Example: `tyfo` | -| frequency
_optional_ | An integer value specifying the frequency within the lookback window that the user has taken the specific action and qualified for the given custom audience.

Type: int

Default value: `1` | -| frequency_comparator
_optional_ | The comparator to the `frequency` passed in the request.

**Note**: In the values below, `GTE` refers to greater than or equal, `LT` to less than, and so on.

Type: string

Possible values: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Default value: `NUM_GTE` | -| negate
_optional_ | Negates the segment and thus is excluded in the combination.

Type: boolean

Default value: `true`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences` -``` - [ - { - "operation_type":"Create", - "params":{ - "name":"my_flexible_audience_name", - "audience_type":"FLEXIBLE", - "segments":{ - "boolean_operator":"AND", - "child_segments":[ - { - "custom_audience_id":"TYIF", - "frequency":1, - "frequency_comparator":"NUM_GT", - "lookback_window":30, - "negate":true, - "child_segments":[ - - ] - }, - { - "boolean_operator":"OR", - "child_segments":[ - { - "custom_audience_id":"TXR1", - "lookback_window":30, - "child_segments":[ - - ] - }, - { - "custom_audience_id":"TYFO", - "frequency":1, - "frequency_comparator":"NUM_GT", - "lookback_window":30, - "negate":true, - "child_segments":[ - - ] - } - ] - } - ] - } - } - } - ] -``` -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "data": { - "targetable": false, - "name": "my_flexible_audience_name", - "targetable_types": [ - "FLEXIBLE", - "EXCLUDED_FLEXIBLE" - ], - "audience_type": "FLEXIBLE", - "id": "13ld7", - "reasons_not_targetable": [ - "PROCESSING", - "TOO_SMALL" - ], - "metadata": [ - { - "custom_audience_id": "13ld7", - "account_id": "qsx3w2", - "name": "my_flexible_audience_name", - "audience_source": "FLEXIBLE_AUDIENCE", - "upload_status": "UPLOADED", - "segments": { - "boolean_operator": "AND", - "frequency": 1, - "frequency_comparator": "NUM_GTE", - "negate": false, - "child_segments": [ - { - "custom_audience_id": "tyif", - "lookback_window": 30, - "frequency": 1, - "frequency_comparator": "NUM_GT", - "negate": true, - "child_segments": [ - - ] - }, - { - "boolean_operator": "OR", - "frequency": 1, - "frequency_comparator": "NUM_GTE", - "negate": false, - "child_segments": [ - { - "custom_audience_id": "txr1", - "lookback_window": 30, - "frequency": 1, - "frequency_comparator": "NUM_GTE", - "negate": false, - "child_segments": [ - - ] - }, - { - "custom_audience_id": "tyfo", - "lookback_window": 30, - "frequency": 1, - "frequency_comparator": "NUM_GT", - "negate": true, - "child_segments": [ - - ] - } - ] - } - ] - } - } - ], - "created_at": "2015-11-10T21:26:43Z", - "updated_at": "2015-11-11T01:11:47Z", - "partner_source": "OTHER", - "deleted": false, - "audience_size": null - }, - "request": [ - { - "params": { - "name": "my_flexible_audience_name", - "audience_type": "FLEXIBLE", - "segments": { - "boolean_operator": "AND", - "child_segments": [ - { - "custom_audience_id": "TYIF", - "lookback_window": 30, - "frequency": 1, - "frequency_comparator": "NUM_GT", - "negate": true, - "child_segments": [ - - ] - }, - { - "boolean_operator": "OR", - "child_segments": [ - { - "custom_audience_id": "TXR1", - "lookback_window": 30, - "child_segments": [ - - ] - }, - { - "custom_audience_id": "TYFO", - "lookback_window": 30, - "frequency": 1, - "frequency_comparator": "NUM_GT", - "negate": true, - "child_segments": [ - - ] - } - ] - } - ] - }, - "account_id": "qsx3w2" - }, - "operation_type": "Create" - } - ] - } -``` -#### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline") - - -Delete the specified Custom Audience belonging to the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | - -**Example Request[](#example-request "Permalink to this headline")** - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "data": { - "targetable": false, - "name": "developers", - "targetable_types": [ - "CRM", - "EXCLUDED_CRM" - ], - "audience_type": "CRM", - "description": null, - "permission_level": "READ_WRITE", - "owner_account_id": "18ce54d4x5t", - "id": "2906h", - "reasons_not_targetable": [ - "TOO_SMALL" - ], - "created_at": "2017-08-22T23:34:26Z", - "updated_at": "2017-08-30T18:09:00Z", - "partner_source": "OTHER", - "deleted": true, - "audience_size": null - }, - "request": { - "params": { - "custom_audience_id": "2906h", - "account_id": "18ce54d4x5t" - } - } - } -``` - -### Do Not Reach Lists - - - -#### GET accounts/:account\_id/do\_not\_reach\_lists[](#get-accounts-account-id-do-not-reach-lists "Permalink to this headline") - -Retrieve details for some or all Do Not Reach List associated with the current account. - -**Note**: An `account_id` can only have at most one Do Not Reach List - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | - -**Example Request[](#example-request "Permalink to this headline")** - -`GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "account_id": "18ce54bgxky" - } - }, - "next_cursor": null, - "data": [ - { - "targetable": false, - "name": "Do Not Reach List", - "description": "test DNRL", - "id": "4kzrq", - "reasons_not_targetable": [ - "TOO_SMALL" - ], - "created_at": "2021-10-28T22:09:29Z", - "list_size": null, - "updated_at": "2021-11-04T03:33:06Z", - "deleted": false - } - ] - } -``` -#### POST accounts/:account\_id/do\_not\_reach\_lists[](#post-accounts-account-id-do-not-reach-lists "Permalink to this headline") - -Create a new Do Not Reach List associated with the current account. - -**Note**: An `account_id` can only have at most one Do Not Reach List - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| description
_optional_ | A description for this audience.

Type: string

Example: `A list of users to exclude` | - -**Example Request[](#example-request "Permalink to this headline")** - -`POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude` - -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "description": "A list of users to exclude", - "account_id": "18ce54bgxky" - } - }, - "data": { - "targetable": false, - "name": "Do Not Reach List", - "description": "A list of users to exclude", - "id": "4ofrq", - "reasons_not_targetable": [ - "PROCESSING", - "TOO_SMALL" - ], - "created_at": "2022-02-08T23:02:48Z", - "list_size": null, - "updated_at": "2022-02-08T23:02:48Z", - "deleted": false - } - } -``` -#### POST batch/accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id/users[](#post-batch-accounts-account-id-do-not-reach-lists-do-not-reach-list-id-users "Permalink to this headline") - -This endpoint allows users to be added, updated and removed from a given `do_not_reach_list_id`. This endpoint only accepts emails as the valid user identifier type. - -All data being provided in the `emails` field of the request must be hashed using `SHA256` and [normalized](/x-ads-api/audiences#e-mail-normalization). - -**Notes** - -* An `account_id` can only have at most one Do Not Reach List -* Users added to this list **must** have an `expires_at` timestamp set to less than 13 months from the current timestamp -* Do Not Reach List API does not accept an `effective_at` timestamp and defaults to the current timestamp -* Do Not Reach List does not remove users from any or all custom audiences in the account but acts as exclusion targeting for all campaigns served for the account - -**Batch Requests** - -* The current maximum batch size is `2500` **for this endpoint**. The batch size is determined by the number of operations (`Update`/`Delete`) per request. For example, over 2500 operation objects (`{"operation_type": "Update/Delete", [..] }`) in one array result in an error. -* The max request POST body size this endpoint can accept is `5,000,000` bytes. -* The rate limits for this endpoint are 1500 per 1 minute window -* 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** - -The response returned by the Ads API contains two fields, a `success_count` and a `total_count`. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is **not** equal the `success_count` and `total_count` should be treated as an error condition, requiring a retry. - -**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 parameters) are show in the response under the `operation_errors` object. -* The index of the error in the `operation_errors` refers to the index in the input item, with the corresponding error message - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users` - -**Parameters[](#parameters "Permalink to this headline")** - -| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | -| do\_not\_reach\_list\_id
_required_ | A reference to the Do Not Reach List you are operating with in the request

Type: string

Example: `2906h` | -| operation_type
_required_ | The per `users` group operation type being performed.

Type: enum

Possible values: `Update`, `Delete` | -| params
_required_ | A JSON object containing the `emails` array and `expires_at` timestamp.

Type: JSON | -| users
_required_ | An array of JSON objects containing all params for an individual user.

Type: JSON | -| expires_at
_optional_ | The UTC time at which the user association(s) should expire. The specified time must be later than the value of the current timestamp. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to 13 months from current timestamp.

Type: string

Example: `2017-07-05T07:00:00Z` | - -Given the mutil-key approach to the `users` object, each element of this object is documented below: - -| Name | Description | -| :--- | :--- | -| email
_optional_ | Email address(es) for the user.

Type: Array\[String\] | -| phone_number
_optional_ | Phone number(s) for the user

Type: Array\[String\] | - -**Example Request[](#example-request "Permalink to this headline")** -``` -`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users` - - [ - { - "operation_type": "Update", - "params": { - "expires_at": "2023-01-22T00:00:00Z", - "users": [ - { - "email": [ - "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC" - ], - "phone_number": [ - "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A" - ] - }, - { - "email": [ - "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA" - ], - "phone_number": [ - "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E" - ] - } - ] - } - } - ] -``` -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "data": [ - { - "success_count": 2, - "total_count": 2 - } - ], - "request": [ - { - "params": { - "do_not_reach_list_id": "4ofrq", - "expires_at": "2023-01-22T00:00:00Z", - "account_id": "18ce54bgxky" - }, - "operation_type": "Update" - } - ] - } -``` -#### DELETE accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id[](#delete-accounts-account-id-do-not-reach-lists-do-not-reach-list-id "Permalink to this headline") - - -Delete the specified Do Not Reach List belonging to the current account. - -**Resource URL[](#resource-url "Permalink to this headline")** - -`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id` - -**Parameters[](#parameters "Permalink to this headline")** - -None - -**Example Request[](#example-request "Permalink to this headline")** +## Full API Reference -`DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp` +For the complete reference (Tailored Audience Permissions, Custom Audiences, Custom Audiences Users, Keyword Insights, Do Not Reach Lists, etc.), see the **[Audiences API Reference](/x-ads-api/audiences/reference)** page. -**Example Response[](#example-response "Permalink to this headline")** -``` - { - "request": { - "params": { - "do_not_reach_list_id": "4ofrp", - "account_id": "18ce54bgxky" - } - }, - "data": { - "targetable": false, - "name": "Do Not Reach List", - "description": null, - "id": "4ofrp", - "reasons_not_targetable": [ - "PROCESSING", - "TOO_SMALL" - ], - "created_at": "2022-02-08T23:02:07Z", - "list_size": null, - "updated_at": "2022-02-08T23:02:21Z", - "deleted": true + diff --git a/x-ads-api/audiences/reference.mdx b/x-ads-api/audiences/reference.mdx new file mode 100644 index 000000000..72550a1af --- /dev/null +++ b/x-ads-api/audiences/reference.mdx @@ -0,0 +1,1336 @@ +--- +title: Audiences API Reference +sidebarTitle: API Reference +description: Complete technical reference for all Audiences endpoints in the X Ads API — Tailored Audiences, Custom Audiences, Audience Permissions, Users in Audiences, Keyword Insights, Do Not Reach Lists, and targeting permissions. +keywords: ["audiences api", "tailored audience api", "custom audience reference", "audience permissions", "x ads audience api"] +--- + +## API Reference + +### Keyword Insights + + +#### GET insights/keywords/search[](#get-insights-keywords-search "Permalink to this headline") + +Given a group of keywords, get the associated Tweet volume as well as a set of 30 related keywords. The Tweet volume corresponds to the input keywords only, not the related keywords. + +A maximum time range (`end_time` \- `start_time`) of 7 days is allowed. + +Please note that results are scoped by a single geo (country). + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/insights/keywords/search` + +**Parameters[](#parameters "Permalink to this headline")** + +| Name | Description | +| :--- | :--- | +| granularity
_required_ | Specifies the granularity of the data returned for the time range denoted by `start_time` and `end_time`. For instance, when set to `HOUR`, you will be presented with a datapoint for each hour between `start_time` and `end_time`. request.

Type: enum

Possible values: `DAY`, `HOUR` | +| keywords
_required_ | A comma-separated string of keywords to narrow search by. All keywords are OR'ed with one another.

**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.

Type: string

Example: `developers` | +| start_time
_required_ | Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

Type: string

Example: `2017-07-10T00:00:00Z` | +| end_time
_optional_ | Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

**Note**: Defaults to the current time.

Type: string

Example: `2017-07-11T00:00:00Z` | +| location
_optional_ | A targeting value you would get from the [GET targeting_criteria/locations](/x-ads-api/campaign-management/reference#get-targeting-criteria-locations) endpoint to narrow results in terms of where the user of the account is located. Note that at present only country level locations are supported.

Type: string

Example: `0ce8b9a7b2742f7e` | +| negative_keywords
_optional_ | A comma-separated string of keywords to exclude. All negative keywords are OR'ed with one another.

**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.

Type: string

Example: `rain` | + +**Example Request[](#example-request "Permalink to this headline")** + +```json +GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01 +``` + +**Example Response[](#example-response "Permalink to this headline")*** +``` + { + "request": { + "params": { + "start_time": "2018-02-01T00:00:00Z", + "end_time": "2018-02-02T00:00:00Z", + "granularity": "DAY", + "keywords": [ + "developers" + ] + } + }, + "data": { + "related_keywords": [ + "dev", + "developer", + "coders", + "mysql", + "devs", + "#technology", + "#developers", + "security", + "programmers", + "#tech", + "javascript", + "#iot", + "#bigdata", + "cloud", + "devops", + "php", + "developer", + "programmer", + "engineer", + "big data", + "agile", + "app", + "programming", + "ios", + "maker", + "startups", + "developer's", + "java", + "#devops", + "startup" + ], + "tweet_volume": [ + 15707 + ] + } + } +``` + +### Tailored Audience Permissions + + + +#### GET accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#get-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline") + +Retrieve details for some or all permissions associated with the specified tailored audience. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| tailored\_audience\_id
_required_ | A reference to the tailored audience you are operating with in the request.

Type: string

Example: `1nmth` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| granted\_account\_ids
_optional_ | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `18ce54aymz3` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.

Type: string

Example: `created_at-asc` | +| tailored\_audience\_permission_ids
_optional_ | Scope the response to just the desired tailored audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `ri` | +| 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "tailored_audience_id": "1nmth" + } + }, + "next_cursor": null, + "data": [ + { + "tailored_audience_id": "1nmth", + "permission_level": "READ_ONLY", + "id": "ri", + "created_at": "2017-06-08T23:17:59Z", + "granted_account_id": "18ce54aymz3", + "updated_at": "2017-06-08T23:17:59Z", + "deleted": false + } + ] + } + +``` +#### POST accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#post-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline") + +Create a new permission object allowing the specified audience to be shared with a given account. + +**Note**: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the `is_owner` response attribute in the response for a given audience. + +**Note**: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the `SHARE_AUDIENCE_OUTSIDE_BUSINESS` account feature. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| granted\_account\_id
_required_ | The account you wish to grant the tailored audience permissions for.

Type: string

Example: `18ce54aymz3` | +| permission_level
_required_ | The type of access to the tailored audience that the `granted_account_id` should have.

Type: enum

Possible values: `READ_ONLY`, `READ_WRITE` | +| tailored\_audience\_id
_required_ | A reference to the tailored audience you are operating with in the request.

Type: string

Example: `2906h` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "granted_account_id": "18ce54aymz3", + "permission_level": "READ_ONLY", + "tailored_audience_id": "2906h" + } + }, + "data": { + "tailored_audience_id": "2906h", + "permission_level": "READ_ONLY", + "id": "14m", + "created_at": "2017-09-12T23:49:34Z", + "granted_account_id": "18ce54aymz3", + "updated_at": "2017-09-12T23:49:34Z", + "deleted": false + } + } +``` + +#### DELETE accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions/:tailored\_audience\_permission_id[](#delete-accounts-account-id-tailored-audiences-tailored-audience-id-permissions-tailored-audience-permission-id "Permalink to this headline") + +Revoke the specified Tailored Audience sharing permission. + +**Note**: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the `is_owner` response attribute in the response for a given audience. + +When revoked, we guarantee that the granted account (`granted_account_id`) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| tailored\_audience\_id
_required_ | A reference to the tailored audience you are operating with in the request.

Type: string

Example: `1nmth` | +| tailored\_audience\_permission_id
_required_ | A reference to the tailored audience permission you are operating with in the request.

Type: string

Example: `ri` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "tailored_audience_permission_id": "ri", + "tailored_audience_id": "1nmth" + } + }, + "data": { + "tailored_audience_id": "1nmth", + "permission_level": "READ_ONLY", + "id": "ri", + "created_at": "2017-06-08T23:17:59Z", + "granted_account_id": "18ce54aymz3", + "updated_at": "2017-08-30T18:29:35Z", + "deleted": true + } + } +``` + +### Targeted Audiences + +#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/targeted[](#get-accounts-account-id-custom-audiences-custom-audience-id-targeted "Permalink to this headline") + +Retrieve a list of active or all line items and campaigns that target a given `custom_audience_id` + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | +| with_active
_optional_ | When `false`, includes line items that have `servable=false` status

Type: boolean

Default: `true`
Possible values: `true`, `false` | +| cursor
_optional_ | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "custom_audience_id": "2906h", + } + }, + "next_cursor": null, + "data": [ + { + "campaign_id": "59hod", + "campaign_name": "test-campaign", + "line_items": [ + { + "id": "5gzog", + "name": "test-line-item", + "servable": true + } + ] + }, + { + "campaign_id": "arja7", + "campaign_name": "Untitled campaign", + "line_items": [ + { + "id": "bjw1q", + "name": null, + "servable": true + } + ] + } + ] + } +``` + +### Custom Audiences Users + + +#### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users[](#post-accounts-account-id-custom-audiences-custom-audience-id-users "Permalink to this headline") + +This endpoint will allow partners to add, update and remove users from a given `custom_audience_id`. The endpoint will also accept multiple user identifier types per user as well. + +All data being provided in the `users` field of the request **except** `partner_user_id` must be hashed using `SHA256` and [normalized](/x-ads-api/audiences/reference#twitter-user-id-normalization). + +**Batch Requests** + +* The current maximum batch size is `2500` **for this endpoint**. The batch size is determined by the number of operations (`Update`/`Delete`) per request. For example, over 2500 operation objects (`{"operation_type": "Update/Delete", [..] }`) in one array result in an error. +* The max request POST body size this endpoint can accept is `5,000,000` bytes. +* The rate limits for this endpoint are 1500 per 1 minute window +* 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** + +The response returned by the Ads API contains two fields, a `success_count` and a `total_count`. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is **not** equal the `success_count` and `total_count` should be treated as an error condition, requiring a retry. + +**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 parameters) are show in the response under the `operation_errors` object. +* The index of the error in the `operation_errors` refers to the index in the input item, with the corresponding error message + +#### Resource URL[](#resource-url "Permalink to this headline") + +`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users` + +#### Parameters[](#parameters "Permalink to this headline") + +| Name | Description | +| :--- | :--- | +| operation_type
_required_ | The per `users` group operation type being performed.

Type: enum

Possible values: `Update`, `Delete` | +| params
_required_ | A JSON object containing the `users` array, the `effective_at` and `expires_at` timestamps.

Type: JSON | +| users
_required_ | An array of JSON objects containing all params for an individual user.

Type: JSON | +| effective_at
_optional_ | The UTC time at which the custom audience association(s) should take effect. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to the current date and time.

Type: string

Example: `2017-07-05T07:00:00Z` | +| expires_at
_optional_ | The UTC time at which the custom audience association(s) should expire. The specified time must be later than the value of `effective_at`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to 13 months from the request timestamp.

Type: string

Example: `2017-07-05T07:00:00Z` | + +Given the mutil-key approach to the `users` object, each element of this object is documented below: + +| Name | Description | +| :--- | :--- | +| email
_optional_ | Email address(es) for the user.

Type: Array\[String\] | +| device_id
_optional_ | IDFA/AdID/Android ID

Type: Array\[String\] | +| handle
_optional_ | The @handle(s) belonging to the user

Type: Array\[String\] | +| twitter_id
_optional_ | The X ID belonging to the user

Type: Array\[String\] | +| phone_number
_optional_ | Phone number(s) for the user

Type: Array\[String\] | +| partner\_user\_id
_optional_ | The user's ID in the partners' system.

Type: Array\[String\] | + +#### Example Request[](#example-request "Permalink to this headline") + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users` +``` + [ + { + "operation_type": "Update", + "params": { + "effective_at": "2018-05-15T00:00:00Z", + "expires_at": "2019-01-01T07:00:00Z", + "users": [ + { + "email": [ + "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3" + ], + "handle": [ + "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb", + "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d" + ] + }, + { + "email": [ + "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c" + ], + "twitter_id": [ + "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf", + "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85" + ] + } + ] + } + }, + { + "operation_type": "Delete", + "params": { + "effective_at": "2018-05-15T00:00:00Z", + "expires_at": "2019-01-01T07:00:00Z", + "users": [ + { + "device_id": [ + "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92" + ], + "email": [ + "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3" + ], + "handle": [ + "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847" + ], + "twitter_id": [ + "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b" + ] + }, + { + "email": [ + "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c" + ], + "twitter_id": [ + "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5", + "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8" + ] + } + ] + } + } + ] +``` +#### Example Response[](#example-response "Permalink to this headline") +``` + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "custom_audience_id": "1nmth" + } + }, + "data": { + "success_count": 4, + "total_count": 4 + } + } +``` + +### Custom Audience Permissions + + + +#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#get-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline") + +Retrieve details for some or all permissions associated with the specified custom audience. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `1nmth` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| granted\_account\_ids
_optional_ | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `18ce54aymz3` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.

Type: string

Example: `created_at-asc` | +| custom\_audience\_permission_ids
_optional_ | Scope the response to just the desired custom audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `ri` | +| 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "custom_audience_id": "1nmth" + } + }, + "next_cursor": null, + "data": [ + { + "custom_audience_id": "1nmth", + "permission_level": "READ_ONLY", + "id": "ri", + "created_at": "2017-06-08T23:17:59Z", + "granted_account_id": "18ce54aymz3", + "updated_at": "2017-06-08T23:17:59Z", + "deleted": false + } + ] + } +``` +#### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#post-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline") + +Create a new permission object allowing the specified audience to be shared with a given account. + +**Note**: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the `is_owner` response attribute in the response for a given audience. + +**Note**: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the `SHARE_AUDIENCE_OUTSIDE_BUSINESS` account feature. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| granted\_account\_id
_required_ | The account you wish to grant the custom audience permissions for.

Type: string

Example: `18ce54aymz3` | +| permission_level
_required_ | The type of access to the custom audience that the `granted_account_id` should have.

Type: enum

Possible values: `READ_ONLY`, `READ_WRITE` | +| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | + +**Example Request[](#example-request "Permalink to this headline")** + +``` +POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY +``` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "granted_account_id": "18ce54aymz3", + "permission_level": "READ_ONLY", + "custom_audience_id": "2906h" + } + }, + "data": { + "custom_audience_id": "2906h", + "permission_level": "READ_ONLY", + "id": "14m", + "created_at": "2017-09-12T23:49:34Z", + "granted_account_id": "18ce54aymz3", + "updated_at": "2017-09-12T23:49:34Z", + "deleted": false + } + } +``` +#### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions/:custom\_audience\_permission_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id-permissions-custom-audience-permission-id "Permalink to this headline") + +Revoke the specified Custom Audience sharing permission. + +**Note**: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the `is_owner` response attribute in the response for a given audience. + +When revoked, we guarantee that the granted account (`granted_account_id`) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `1nmth` | +| custom\_audience\_permission_id
_required_ | A reference to the custom audience permission you are operating with in the request.

Type: string

Example: `ri` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "account_id": "18ce54d4x5t", + "custom_audience_permission_id": "ri", + "custom_audience_id": "1nmth" + } + }, + "data": { + "custom_audience_id": "1nmth", + "permission_level": "READ_ONLY", + "id": "ri", + "created_at": "2017-06-08T23:17:59Z", + "granted_account_id": "18ce54aymz3", + "updated_at": "2017-08-30T18:29:35Z", + "deleted": true + } + } +``` + +### Custom Audiences + + +#### GET accounts/:account\_id/custom\_audiences[](#get-accounts-account-id-custom-audiences "Permalink to this headline") + +Retrieve details for some or all Custom Audiences associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/custom_audiences` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| 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](/x-ads-api/introduction) for more information.

Type: string

Example: `8x7v00oow` | +| permission_scope
_optional_ | Allows filtering the response to lists you own or lists that have been shared with you. By default, without specifying this parameter you will only see audiences you own.

Type: enum

Default: `OWNER`
Possible values: `OWNER`, `SHARED` | +| q
_optional_ | An optional query to scope resource by `name`.

**Note**: This performs case-insensitive prefix matching.

Type: string

Min, Max length: `1`, `255` | +| sort_by
_optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.

Type: string

Example: `created_at-asc` | +| custom\_audience\_ids
_optional_ | Scope the response to just the desired custom audiences by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: `1nmth` | +| 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 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[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "custom_audience_ids": [ + "1nmth" + ], + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "targetable": true, + "name": "twurl-using-subshell-for-file", + "targetable_types": [ + "CRM", + "EXCLUDED_CRM" + ], + "audience_type": "CRM", + "description": null, + "permission_level": "READ_WRITE", + "owner_account_id": "18ce54d4x5t", + "id": "1nmth", + "reasons_not_targetable": [], + "created_at": "2017-01-08T08:19:58Z", + "updated_at": "2017-01-08T16:21:13Z", + "partner_source": "OTHER", + "deleted": false, + "audience_size": 1470 + } + ] + } +``` +#### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#get-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline") + +Retrieve specific Custom Audiences associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "custom_audience_id": "2906h", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "targetable": false, + "name": "developers", + "targetable_types": [ + "CRM", + "EXCLUDED_CRM" + ], + "audience_type": "CRM", + "description": null, + "permission_level": "READ_WRITE", + "owner_account_id": "18ce54d4x5t", + "id": "2906h", + "reasons_not_targetable": [], + "created_at": "2017-08-22T23:34:26Z", + "updated_at": "2017-08-22T23:34:26Z", + "partner_source": "OTHER", + "deleted": false, + "audience_size": 140321 + } + } +``` +#### POST accounts/:account\_id/custom\_audiences[](#post-accounts-account-id-custom-audiences "Permalink to this headline") + +Create a new placeholder Custom Audience associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/custom_audiences` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| name
_required_ | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.

Type: string

Example: `ads api users` | +| description
_optional_ | A description for this audience.

Type: string

Example: `Collection of all users of the Ads API` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "data": { + "targetable": false, + "name": "developers", + "targetable_types": [ + "CRM", + "EXCLUDED_CRM" + ], + "audience_type": "CRM", + "description": null, + "permission_level": "READ_WRITE", + "owner_account_id": "18ce54d4x5t", + "id": "2906h", + "reasons_not_targetable": [ + "PROCESSING", + "TOO_SMALL" + ], + "created_at": "2017-08-22T23:34:26Z", + "updated_at": "2017-08-22T23:34:26Z", + "partner_source": "OTHER", + "deleted": false, + "audience_size": null + }, + "request": { + "params": { + "account_id": "18ce54d4x5t", + "name": "developers" + } + } + } +``` +#### PUT accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#put-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline") + +Update the specfic Custom Audience associated with the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| custom\_audience\_id
_required_ | A reference to the Custom Audience you are operating with in the request

Type: string

Example: `2906h` | +| name
_optional_ | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.

Type: string

Example: `ads api users` | +| description
_optional_ | A description for this audience.

Type: string

Example: `Collection of all users of the Ads API` | + +**Example Request[](#example-request "Permalink to this headline")** + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "data": { + "targetable": false, + "name": "developers_changed", + "targetable_types": [ + "CRM", + "EXCLUDED_CRM" + ], + "audience_type": "CRM", + "description": null, + "permission_level": "READ_WRITE", + "is_owner": true, + "id": "2906h", + "reasons_not_targetable": [ + "PROCESSING", + "TOO_SMALL" + ], + "created_at": "2017-08-22T23:34:26Z", + "updated_at": "2017-08-22T23:34:26Z", + "partner_source": "OTHER", + "deleted": false, + "audience_size": null + }, + "request": { + "params": { + "account_id": "18ce54d4x5t", + "name": "developers_changed" + } + } + } +``` +#### POST batch/accounts/:account\_id/custom\_audiences[](#post-batch-accounts-account-id-custom-audiences "Permalink to this headline") + +Allows for batch creation of Custom Audiences. See the [Custom Audiences Overview](/x-ads-api/audiences) page for information on audiences. + +**Note:** This batch endpoint is currently in **closed beta** and available to select advertisers. During this beta period, only Flexible Audiences based on mobile custom audiences can be created. + +**Batch Requests** + +* The current maximum batch size is 10. +* 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 parameter) are shown in the response under the `operation_errors` object. + +**Flexible Audiences** + + +* Flexible Audiences are immutable once created. +* Custom Audiences are passed in a tree structure with boolean logic combinations to create Flexible Audiences +* A maximum of 10 Custom Audiences leaf nodes can be used to create a Flexible Audience. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| audience_type
_required_ | The type of audience to create.

Type: enum

Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE` | +| child_segments
_required_ | An array containing objects which define the subset of a Custom Audience's members that you would like to target. Each object should contain a `custom_audience_id`, `frequency`, `frequency_comparator`, `lookback_window`, `negate`, and, in some cases, additional `child_segments`.

Type: array | +| name
_required_ | The display name for the audience. Unique name value must be used. Failure to do so will result in an error.

Type: string

Example: `my_flexible_audience_name` | +| operation_type
_required_ | The per item operation type being performed.

Type: enum

Possible values: `Create`, `Update`, `Delete` | +| boolean_operator
_sometimes required_ | The logical relationship between the child segments in its parent (containing) object. Required if child_segments is non-empty for the parent object.

Type: enum

Possible values: `AND`, `OR` | +| lookback_window
_sometimes required_ | An integer value specifying the range of days within which the user has taken the specific action and qualified for the given custom audience.

Type: int

Possible values: `1`, `7`, `14`, `30` | +| segments
_sometimes required_ | An object containing a `boolean_operator` and `child_segments` which define the subset of a Custom Audience's members that you would like to target.

Type: object | +| custom\_audience\_id
_sometimes required_ | The id of the custom audience to use as a child segment.

Type: string

Example: `tyfo` | +| frequency
_optional_ | An integer value specifying the frequency within the lookback window that the user has taken the specific action and qualified for the given custom audience.

Type: int

Default value: `1` | +| frequency_comparator
_optional_ | The comparator to the `frequency` passed in the request.

**Note**: In the values below, `GTE` refers to greater than or equal, `LT` to less than, and so on.

Type: string

Possible values: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Default value: `NUM_GTE` | +| negate
_optional_ | Negates the segment and thus is excluded in the combination.

Type: boolean

Default value: `true`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences` +``` + [ + { + "operation_type":"Create", + "params":{ + "name":"my_flexible_audience_name", + "audience_type":"FLEXIBLE", + "segments":{ + "boolean_operator":"AND", + "child_segments":[ + { + "custom_audience_id":"TYIF", + "frequency":1, + "frequency_comparator":"NUM_GT", + "lookback_window":30, + "negate":true, + "child_segments":[ + + ] + }, + { + "boolean_operator":"OR", + "child_segments":[ + { + "custom_audience_id":"TXR1", + "lookback_window":30, + "child_segments":[ + + ] + }, + { + "custom_audience_id":"TYFO", + "frequency":1, + "frequency_comparator":"NUM_GT", + "lookback_window":30, + "negate":true, + "child_segments":[ + + ] + } + ] + } + ] + } + } + } + ] +``` +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "data": { + "targetable": false, + "name": "my_flexible_audience_name", + "targetable_types": [ + "FLEXIBLE", + "EXCLUDED_FLEXIBLE" + ], + "audience_type": "FLEXIBLE", + "id": "13ld7", + "reasons_not_targetable": [ + "PROCESSING", + "TOO_SMALL" + ], + "metadata": [ + { + "custom_audience_id": "13ld7", + "account_id": "qsx3w2", + "name": "my_flexible_audience_name", + "audience_source": "FLEXIBLE_AUDIENCE", + "upload_status": "UPLOADED", + "segments": { + "boolean_operator": "AND", + "frequency": 1, + "frequency_comparator": "NUM_GTE", + "negate": false, + "child_segments": [ + { + "custom_audience_id": "tyif", + "lookback_window": 30, + "frequency": 1, + "frequency_comparator": "NUM_GT", + "negate": true, + "child_segments": [ + + ] + }, + { + "boolean_operator": "OR", + "frequency": 1, + "frequency_comparator": "NUM_GTE", + "negate": false, + "child_segments": [ + { + "custom_audience_id": "txr1", + "lookback_window": 30, + "frequency": 1, + "frequency_comparator": "NUM_GTE", + "negate": false, + "child_segments": [ + + ] + }, + { + "custom_audience_id": "tyfo", + "lookback_window": 30, + "frequency": 1, + "frequency_comparator": "NUM_GT", + "negate": true, + "child_segments": [ + + ] + } + ] + } + ] + } + } + ], + "created_at": "2015-11-10T21:26:43Z", + "updated_at": "2015-11-11T01:11:47Z", + "partner_source": "OTHER", + "deleted": false, + "audience_size": null + }, + "request": [ + { + "params": { + "name": "my_flexible_audience_name", + "audience_type": "FLEXIBLE", + "segments": { + "boolean_operator": "AND", + "child_segments": [ + { + "custom_audience_id": "TYIF", + "lookback_window": 30, + "frequency": 1, + "frequency_comparator": "NUM_GT", + "negate": true, + "child_segments": [ + + ] + }, + { + "boolean_operator": "OR", + "child_segments": [ + { + "custom_audience_id": "TXR1", + "lookback_window": 30, + "child_segments": [ + + ] + }, + { + "custom_audience_id": "TYFO", + "lookback_window": 30, + "frequency": 1, + "frequency_comparator": "NUM_GT", + "negate": true, + "child_segments": [ + + ] + } + ] + } + ] + }, + "account_id": "qsx3w2" + }, + "operation_type": "Create" + } + ] + } +``` +#### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline") + + +Delete the specified Custom Audience belonging to the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| custom\_audience\_id
_required_ | A reference to the custom audience you are operating with in the request.

Type: string

Example: `2906h` | + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "data": { + "targetable": false, + "name": "developers", + "targetable_types": [ + "CRM", + "EXCLUDED_CRM" + ], + "audience_type": "CRM", + "description": null, + "permission_level": "READ_WRITE", + "owner_account_id": "18ce54d4x5t", + "id": "2906h", + "reasons_not_targetable": [ + "TOO_SMALL" + ], + "created_at": "2017-08-22T23:34:26Z", + "updated_at": "2017-08-30T18:09:00Z", + "partner_source": "OTHER", + "deleted": true, + "audience_size": null + }, + "request": { + "params": { + "custom_audience_id": "2906h", + "account_id": "18ce54d4x5t" + } + } + } +``` + +### Do Not Reach Lists + + + +#### GET accounts/:account\_id/do\_not\_reach\_lists[](#get-accounts-account-id-do-not-reach-lists "Permalink to this headline") + +Retrieve details for some or all Do Not Reach List associated with the current account. + +**Note**: An `account_id` can only have at most one Do Not Reach List + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| with_deleted
_optional_ | Include deleted results in your request.

Type: boolean

Default: `false`
Possible values: `true`, `false` | + +**Example Request[](#example-request "Permalink to this headline")** + +`GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "account_id": "18ce54bgxky" + } + }, + "next_cursor": null, + "data": [ + { + "targetable": false, + "name": "Do Not Reach List", + "description": "test DNRL", + "id": "4kzrq", + "reasons_not_targetable": [ + "TOO_SMALL" + ], + "created_at": "2021-10-28T22:09:29Z", + "list_size": null, + "updated_at": "2021-11-04T03:33:06Z", + "deleted": false + } + ] + } +``` +#### POST accounts/:account\_id/do\_not\_reach\_lists[](#post-accounts-account-id-do-not-reach-lists "Permalink to this headline") + +Create a new Do Not Reach List associated with the current account. + +**Note**: An `account_id` can only have at most one Do Not Reach List + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| description
_optional_ | A description for this audience.

Type: string

Example: `A list of users to exclude` | + +**Example Request[](#example-request "Permalink to this headline")** + +`POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "description": "A list of users to exclude", + "account_id": "18ce54bgxky" + } + }, + "data": { + "targetable": false, + "name": "Do Not Reach List", + "description": "A list of users to exclude", + "id": "4ofrq", + "reasons_not_targetable": [ + "PROCESSING", + "TOO_SMALL" + ], + "created_at": "2022-02-08T23:02:48Z", + "list_size": null, + "updated_at": "2022-02-08T23:02:48Z", + "deleted": false + } + } +``` +#### POST batch/accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id/users[](#post-batch-accounts-account-id-do-not-reach-lists-do-not-reach-list-id-users "Permalink to this headline") + +This endpoint allows users to be added, updated and removed from a given `do_not_reach_list_id`. This endpoint only accepts emails as the valid user identifier type. + +All data being provided in the `emails` field of the request must be hashed using `SHA256` and [normalized](/x-ads-api/audiences/reference#e-mail-normalization). + +**Notes** + +* An `account_id` can only have at most one Do Not Reach List +* Users added to this list **must** have an `expires_at` timestamp set to less than 13 months from the current timestamp +* Do Not Reach List API does not accept an `effective_at` timestamp and defaults to the current timestamp +* Do Not Reach List does not remove users from any or all custom audiences in the account but acts as exclusion targeting for all campaigns served for the account + +**Batch Requests** + +* The current maximum batch size is `2500` **for this endpoint**. The batch size is determined by the number of operations (`Update`/`Delete`) per request. For example, over 2500 operation objects (`{"operation_type": "Update/Delete", [..] }`) in one array result in an error. +* The max request POST body size this endpoint can accept is `5,000,000` bytes. +* The rate limits for this endpoint are 1500 per 1 minute window +* 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** + +The response returned by the Ads API contains two fields, a `success_count` and a `total_count`. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is **not** equal the `success_count` and `total_count` should be treated as an error condition, requiring a retry. + +**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 parameters) are show in the response under the `operation_errors` object. +* The index of the error in the `operation_errors` refers to the index in the input item, with the corresponding error message + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users` + +**Parameters[](#parameters "Permalink to this headline")** + +| 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](/x-ads-api/campaign-management/reference#accounts). The specified account must be associated with the authenticated user.

Type: string

Example: `18ce54d4x5t` | +| do\_not\_reach\_list\_id
_required_ | A reference to the Do Not Reach List you are operating with in the request

Type: string

Example: `2906h` | +| operation_type
_required_ | The per `users` group operation type being performed.

Type: enum

Possible values: `Update`, `Delete` | +| params
_required_ | A JSON object containing the `emails` array and `expires_at` timestamp.

Type: JSON | +| users
_required_ | An array of JSON objects containing all params for an individual user.

Type: JSON | +| expires_at
_optional_ | The UTC time at which the user association(s) should expire. The specified time must be later than the value of the current timestamp. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to 13 months from current timestamp.

Type: string

Example: `2017-07-05T07:00:00Z` | + +Given the mutil-key approach to the `users` object, each element of this object is documented below: + +| Name | Description | +| :--- | :--- | +| email
_optional_ | Email address(es) for the user.

Type: Array\[String\] | +| phone_number
_optional_ | Phone number(s) for the user

Type: Array\[String\] | + +**Example Request[](#example-request "Permalink to this headline")** +``` +`POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users` + + [ + { + "operation_type": "Update", + "params": { + "expires_at": "2023-01-22T00:00:00Z", + "users": [ + { + "email": [ + "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC" + ], + "phone_number": [ + "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A" + ] + }, + { + "email": [ + "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA" + ], + "phone_number": [ + "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E" + ] + } + ] + } + } + ] +``` +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "data": [ + { + "success_count": 2, + "total_count": 2 + } + ], + "request": [ + { + "params": { + "do_not_reach_list_id": "4ofrq", + "expires_at": "2023-01-22T00:00:00Z", + "account_id": "18ce54bgxky" + }, + "operation_type": "Update" + } + ] + } +``` +#### DELETE accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id[](#delete-accounts-account-id-do-not-reach-lists-do-not-reach-list-id "Permalink to this headline") + + +Delete the specified Do Not Reach List belonging to the current account. + +**Resource URL[](#resource-url "Permalink to this headline")** + +`https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id` + +**Parameters[](#parameters "Permalink to this headline")** + +None + +**Example Request[](#example-request "Permalink to this headline")** + +`DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp` + +**Example Response[](#example-response "Permalink to this headline")** +``` + { + "request": { + "params": { + "do_not_reach_list_id": "4ofrp", + "account_id": "18ce54bgxky" + } + }, + "data": { + "targetable": false, + "name": "Do Not Reach List", + "description": null, + "id": "4ofrp", + "reasons_not_targetable": [ + "PROCESSING", + "TOO_SMALL" + ], + "created_at": "2022-02-08T23:02:07Z", + "list_size": null, + "updated_at": "2022-02-08T23:02:21Z", + "deleted": true + } + } +``` \ No newline at end of file diff --git a/x-ads-api/campaign-management.mdx b/x-ads-api/campaign-management.mdx index 99ab59741..a2830bd6b 100644 --- a/x-ads-api/campaign-management.mdx +++ b/x-ads-api/campaign-management.mdx @@ -11,6 +11,13 @@ import { Button } from '/snippets/button.mdx'; Campaigns define your budget and schedule. Line items (also called ad groups) control targeting, bidding, and the creatives that run within a campaign. + + Looking for detailed endpoint documentation?
+ The full API reference (all endpoints, request/response examples, and parameter tables for Accounts, Campaigns, Line Items, Funding Instruments, Targeting, etc.) has moved to the dedicated{" "} + Campaign Management API Reference page. + Old deep links (e.g. #get-accounts-account-id-campaigns) will automatically redirect there. + + ## Quick Links - [What Can You Promote?](#what-can-you-promote) @@ -28,7 +35,7 @@ Programatically schedule campaigns and manage ads on X through this suite of API - Promoted Ads are ordinary ads purchased by advertisers who want to reach a wider group of users or to spark engagement from their existing followers. - Promoted Ads are clearly labeled as Promoted when an advertiser is paying for their placement on X. In every other respect, Promoted Ads act just like regular ads and can be reposted, replied to, liked and more. They have typical delivery rules and are created using [POST statuses/update](/x-api/posts/creation-of-a-post). -- **“Promoted-only” Tweets,** created via [POST accounts/:account_id/tweet](/x-ads-api/creatives#post-accounts-account-id-tweet), can be used in Promoted Tweets campaigns but will not serve to followers or appear on the public timeline. To retrieve a list of promoted-only tweets for a certain account, use [GET accounts/:account_id/scoped_timeline](/x-ads-api/creatives). +- **“Promoted-only” Tweets,** created via [POST accounts/:account_id/tweet](/x-ads-api/creatives/reference#post-accounts-account-id-tweet), can be used in Promoted Tweets campaigns but will not serve to followers or appear on the public timeline. To retrieve a list of promoted-only tweets for a certain account, use [GET accounts/:account_id/scoped_timeline](/x-ads-api/creatives). ### [Promoted Accounts](https://business.x.com/help/what-are-promoted-accounts) @@ -486,7 +493,7 @@ For possible placement combinations, refer to the [GET line_items/placements](/x **Followers Of**: Target the followers of any fully promotable users for the current account (note, currently the primary account holder is the only fully-promotable user of that account). [GET accounts/:account\_id/promotable\_users](/x-ads-api/campaign-management/reference#get-accounts-account-id-promotable-users) to get a list of promotable users. -[Similar to Followers Of](https://business.x.com/help/interest-and-username-targeting): Target people with the same interests as followers of specific users. You can use up to 100 [Users](/x-api/fundamentals/data-dictionary#user). +[Similar to Followers Of](https://business.x.com/help/interest-and-username-targeting): Target people with the same interests as followers of specific users. You can use up to 100 [Users](/x-api/fundamentals/data-dictionary/reference#user). [Locations](https://business.x.com/help/geo-gender-and-language-targeting): Specify up to 2,000 locations to target. Get list from [GET targeting_criteria/locations](/x-ads-api/campaign-management/reference#get-targeting-criteria-locations). There are additional requirements for ads that target certain countries. See [Country Targeting and Display Requirements](/x-ads-api/campaign-management/reference#country-targeting-and-display-requirements) for more information. @@ -917,7 +924,7 @@ The following guide outlines the steps required to set up a PREROLL_VIEWS campai * [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) (for video upload) -* [POST accounts/:account\_id/media\_library](/x-ads-api/creatives#media-library) (for video association to ads account) +* [POST accounts/:account\_id/media\_library](/x-ads-api/creatives/reference#media-library) (for video association to ads account) * [POST accounts/:account_id/campaigns](/x-ads-api/campaign-management/reference#post-accounts-account-id-campaigns) (create campaign) * [GET content_categories](/x-ads-api/campaign-management/reference#content-categories) (to get the mapping of content categories to IAB categories) * [GET accounts/:account\_id/curated\_categories](/x-ads-api/campaign-management/reference#curated-categories-2) @@ -925,7 +932,7 @@ The following guide outlines the steps required to set up a PREROLL_VIEWS campai * [POST accounts/:account\_id/line\_item\_curated\_categories](/x-ads-api/campaign-management/reference#line-item-curated-categories) * [POST accounts/:account\_id/line\_items](/x-ads-api/campaign-management/reference#campaigns) (create ad group) * [POST accounts/:account\_id/media\_creatives](/x-ads-api/campaign-management/reference#post-accounts-account-id-media-creatives) (to associate video with ad group) -* [POST accounts/:account\_id/preroll\_call\_to\_action](/x-ads-api/creatives#preroll-call-to-actions) (set CTA and redirect URL) +* [POST accounts/:account\_id/preroll\_call\_to\_action](/x-ads-api/creatives/reference#preroll-call-to-actions) (set CTA and redirect URL) * [POST batch/accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#post-batch-accounts-account-id-targeting-criteria) (targeting) #### Steps @@ -937,11 +944,11 @@ Uploading the video involves 2 steps: #### Upload the video media -First, using the [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) endpoint, you will upload the video to X for processing. You must pass the `media_category=amplify_video` on the initial `INIT` using this endpoint. You’ll upload the video in chunks. Once the `STATUS` returns a `state` of `succeeded` you may continue with the next steps. More on the uploading of media using the chunked endpoint can be found in our [Promoted Video Overview](/x-ads-api/creatives#promoted-video). +First, using the [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) endpoint, you will upload the video to X for processing. You must pass the `media_category=amplify_video` on the initial `INIT` using this endpoint. You’ll upload the video in chunks. Once the `STATUS` returns a `state` of `succeeded` you may continue with the next steps. More on the uploading of media using the chunked endpoint can be found in our [Promoted Video Overview](/x-ads-api/creatives/reference#promoted-video). #### Add the video to the ads account -Once the state returned using the `STATUS` command is `succeeded`, you’ll use the media_key returned from that endpoint to add the video to the advertiser’s media library, using the [POST accounts/:account\_id/media\_library](/x-ads-api/creatives#media-library) endpoint. +Once the state returned using the `STATUS` command is `succeeded`, you’ll use the media_key returned from that endpoint to add the video to the advertiser’s media library, using the [POST accounts/:account\_id/media\_library](/x-ads-api/creatives/reference#media-library) endpoint. ```json POST https://ads-api.x.com/8/55w3kv/media\_library?media\_key=3_931236738554519552 @@ -1565,7 +1572,7 @@ line\_item\_id=4bii5&account\_media\_id=knb #### Set the CTA and destination URL -It is important to note that unlike most other campaigns on X, the `VIDEO_VIEWS_PREROLL` objective does not utilize Promoted Tweets or Cards. Instead, the video creative is associated with your ad group (line item) and the CTA information is associated with a `preroll_call_to_action` entity. The [POST accounts/:account\_id/preroll\_call\_to\_action](/x-ads-api/creatives#preroll-call-to-actions) endpoint allows you to control the button CTA and the destination URL. +It is important to note that unlike most other campaigns on X, the `VIDEO_VIEWS_PREROLL` objective does not utilize Promoted Tweets or Cards. Instead, the video creative is associated with your ad group (line item) and the CTA information is associated with a `preroll_call_to_action` entity. The [POST accounts/:account\_id/preroll\_call\_to\_action](/x-ads-api/creatives/reference#preroll-call-to-actions) endpoint allows you to control the button CTA and the destination URL. ```json POST https://ads-api.x.com/8/accounts/55w3kv/preroll\_call\_to_action line\_item\_id=4bii5&call\_to\_action=VISIT\_SITE&call\_to\_action\_url=https%3A%2F%2Fx.com%2FAdsAPI @@ -1707,3 +1714,19 @@ TL;DR: from an API standpoint, this change is quite simple: you can now target k For the complete list of endpoints with request/response examples and attribute tables, see the **[Campaign Management API Reference](/x-ads-api/campaign-management/reference)** page. + + diff --git a/x-ads-api/campaign-management/reference.mdx b/x-ads-api/campaign-management/reference.mdx index 736dc829e..0025a5e40 100644 --- a/x-ads-api/campaign-management/reference.mdx +++ b/x-ads-api/campaign-management/reference.mdx @@ -7,6 +7,11 @@ keywords: ["campaign management api", "ads api reference", "line items api", "ca ## API Reference + + This is the full technical reference. For an overview of campaigns, line items, budgeting, targeting concepts, and a step-by-step getting started guide, see the{" "} + Campaign Management Overview. + + ### Accounts - -#### GET accounts/:account_id/account_media - -Retrieve details for some or all account media associated with the current account. - -#### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/account_media` - -#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | -| account\_media\_ids *optional* | Scope the response to just the desired account media by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `3wpx` | -| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` | -| creative\_types *optional* | Scope the response to just the account media that match the specified creative types. More than one creative type may be specified by comma-separating enum values. Type: enum Possible values: `BANNER`, `BANNER_TABLET`, `INTERSTITIAL`, `INTERSTITIAL_LANDSCAPE`, `INTERSTITIAL_LANDSCAPE_TABLET`, `INTERSTITIAL_TABLET`, `MEDIUM_RECTANGLE`, `PREROLL`, `VAST_PREROLL` | -| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | -| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/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 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/account_media?account_media_ids=3wpx` - -#### Example Response -``` -{ - "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 a specific account media object associated with the current account. - -#### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | -| account\_media\_id *required* | A reference to the account media you are operating with in the request. Type: string Example: `2pnfd` | -| 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/account_media/2pnfd` - -#### Example Response -``` -{ - "request": { - "params": { - "account_media_id": "2pnfd", - "account_id": "18ce54d4x5t" - } - }, - "data": { - "video_id": null, - "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig", - "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", - "id": "2pnfd", - "created_at": "2017-07-28T01:44:41Z", - "updated_at": "2017-07-28T01:44:41Z", - "deleted": false - } -} -``` - -Delete the specified account media object belonging to the current account. - -#### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | -| account\_media\_id *required* | A reference to the account media you are operating with in the request. Type: string Example: `2pnfd` | - -#### Example Request - -`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd` - -#### Example Response -``` -{ - "data": { - "video_id": null, - "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig", - "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", - "id": "2pnfd", - "created_at": "2017-07-28T01:44:41Z", - "updated_at": "2017-08-25T17:16:26Z", - "deleted": true - }, - "request": { - "params": { - "account_id": "18ce54d4x5t", - "account_media_id": "2pnfd" - } - } -} -``` - -### Cards - - - -**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets), or the [POST accounts/:account\_id/draft\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/draft-tweets#post-accounts-account-id-draft-tweets) endpoints. - -Retrieve details for some or all cards associated with the current account. - -**Note**: This only returns cards that were created using the POST accounts/:account\_id/cards endpoint. Cards created using other endpoints are not returned. - -#### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/cards` - -#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | -| card\_types *optional* | Scope the response to just the desired card types by specifying a comma-separated list of enum values. Type: enum Possible values: `IMAGE_APP`, `IMAGE_CAROUSEL_APP`, `IMAGE_CAROUSEL_WEBSITE`, `IMAGE_MULTI_DEST_CAROUSEL_WEBSITE`, `IMAGE_WEBSITE`, `MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE`, `VIDEO_APP`, `VIDEO_CAROUSEL_APP`, `VIDEO_CAROUSEL_WEBSITE`, `VIDEO_MULTI_DEST_CAROUSEL_WEBSITE`, `VIDEO_WEBSITE` | -| card\_id *optional* | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card IDs may be provided. Type: string Example: `1044294149527166979,1044301099031658496` | -| card\_uris *optional* | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: `card://1044294149527166979,card://1044301099031658496` | -| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` | -| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | -| include\_legacy\_cards *optional* | Include legacy website and app cards in the response. Legacy cards are those whose resource URL has the following format: accounts/:account\_id/cards/:card\_type. See [this developer forum post](https://devcommunity.x.com/t/new-cards-endpoints-and-carousel-ads/145782/6) for additional context. Type: boolean Default: `false` Possible values: `true`, `false` | -| q *optional* | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `dtc` | -| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/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` | - -#### Example Request - -`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1` - -#### Example Response -``` -{ - "request": { - "params": { - "count": 1, - "account_id": "18ce54d4x5t" - } - }, - "next_cursor": "8wzvldqtc", - "data": [ - { - "name": "deep link", - "components": [ - { - "type": "SWIPEABLE_MEDIA", - "media_keys": [ - "3_1073727809120419840", - "3_1075096386931052545" - ] - }, - { - "type": "BUTTON", - "label": { - "type": "ENUM", - "value": "OPEN" - }, - "destination": { - "type": "APP", - "country_code": "US", - "googleplay_app_id": "com.twitter.android", - "googleplay_deep_link": "twitter://user?screen_name=apimctestface" - } - } - ], - "created_at": "2020-10-28T20:47:52Z", - "card_uri": "card://1321554298900107264", - "id": "1321554298900107264", - "updated_at": "2020-10-28T20:47:52Z", - "deleted": false, - "card_type": "IMAGE_CAROUSEL_APP" - } - ] -} -``` - -Retrieve details for a single card associated with the current account. - -#### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/cards/:card_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | -| card\_id *required* | The id of the cards. Type: string Example: `1044294149527166979` | -| 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/cards/1321554298900107264` - -#### Example Response -``` -{ - "request": { - "params": { - "account_id": "18ce54d4x5t", - "card_id": "1321554298900107264" - } - }, - "data": [ - { - "name": "deep link", - "components": [ - { - "type": "SWIPEABLE_MEDIA", - "media_keys": [ - "3_1073727809120419840", - "3_1075096386931052545" - ] - }, - { - "type": "BUTTON", - "label": { - "type": "ENUM", - "value": "OPEN" - }, - "destination": { - "type": "APP", - "country_code": "US", - "googleplay_app_id": "com.twitter.android", - "googleplay_deep_link": "twitter://user?screen_name=apimctestface" - } - } - ], - "created_at": "2020-10-28T20:47:52Z", - "card_uri": "card://1321554298900107264", - "id": "1321554298900107264", - "updated_at": "2020-10-28T20:47:52Z", - "deleted": false, - "card_type": "IMAGE_CAROUSEL_APP" - } - ] -} -``` -#### POST accounts/:account_id/cards - -Create a new card associated to the specified account. - -Card create requests only accept JSON POST bodies. The `Content-Type` must be set to `application/json`. - -See our [Carousels Guide](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/carousels) for a detailed usage example. - -#### Resource URL - -`https://ads-api.x.com/12/accounts/:account_id/cards` - -#### Parameters - -The JSON POST body must include a card `name` and an array of `components`. Components are represented as objects and describe the advertiser-facing attributes of the card. - -The following example shows the general structure of the payload (but includes non-working information). - -``` -{ - "name": "some name", - "components": [ - { - "type": "TYPE_ENUM", - "key": "value" - } - ] -} -``` - -Additional information on components below. - -| 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | -| name *required* | The name for the card. Maximum length: 80 characters. Type: string Example: `component based card` | -| components *sometimes required* | Describes the components to use to create the card. Additional information below. Cannot be specified along with `slides`. **Note**: The order of the components is important. Type: array of objects | -| slides *sometimes required* | Use this array of array to create Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with `components`. **Note**: The order of each slide is important. Type: array of array | - -#### Components - -Every component must include a `type` field which determines the object's schema. The Ads API supports the following component types, grouped into media- and description-based components. - -- Media: -- `MEDIA`: single video or image -- `SWIPEABLE_MEDIA`: between 2-6 videos or images -- Description: -- `DETAILS` -- `BUTTON` - -Each component has a set of required fields (in addition to the `type` key). These are listed in the following table. - -| Component `type` | Field | Value type | -| :--- | :--- | :--- | -| `MEDIA` | `media_key` | string | -| `SWIPEABLE_MEDIA` | `media_keys` | array of strings | -| `DETAILS` | `title` `destination` | string object | -| `BUTTON` | `label` `destination` | object object | - -The following is an example of a `BUTTON` component in the context of the `components` array (intentionally omitting the `name` key). (The ellipses indicate places where more information would need to be specified.) - -``` -{ - "components": [ - { - "type": "BUTTON", - "label": { - ... - }, - "destination": { - ... - } - } - ] -} -``` - -The order in which the component objects are specified defines the top-to-bottom order in which they will be rendered. Cards must be created using one media-based component and either a `DETAILS` or `BUTTON` component. Description-based components are rendered under media and have associated destinations, either URLs or mobile apps. - -**Label** - -Labels define the text shown on buttons and, therefore, only apply to the `BUTTON` component. Label objects have two required keys: `type` and `value`. The `type` must be set to `ENUM` and the `value` can be one of: `BOOK`, `CONNECT`, `INSTALL`, `OPEN`, `ORDER`, `PLAY`, or `SHOP`. - -Building on the previous example, the following shows the `label` object within the `BUTTON` component. - -``` -{ - "components": [ - { - "type": "BUTTON", - "label": { - "type": "ENUM", - "value": "INSTALL" - }, - "destination": { - ... - } - } - ] -} -``` - -**Destination** - -Destinations are where advertisers intend to take users. They are always required within `DETAILS` or `BUTTON` components. There are two destination types: `WEBSITE` or `APP`. - -**Note**: Website destinations can only be used with `DETAILS` components and app destinations can only be used with `BUTTON` components. - -**Website Destination** - -| Name | Description | -| :--- | :--- | -| type *required* | The destination type, which determines its schema. Type: enum Possible values: `WEBSITE` | -| url *required* | The URL of the website to redirect a user to. Type: string Example: `https://devcommunity.x.com/c/advertiser-api` | - -**App Destination** - -| Name | Description | -| :--- | :--- | -| type *required* | The destination type, which determines its schema. Type: enum Possible values: `APP` | -| country\_code *required* | The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) two-letter code for the country where the app is sold. Type: string Example: `US` | -| googleplay\_app\_id *sometimes required* | The Google Play application package name. **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `com.twitter.android` | -| ios\_app\_store\_identifier *sometimes required* | The iOS app store identifier. **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `333903271` | -| googleplay\_deep\_link *optional* | A deep link into the Android app you're promoting. **Note**: Can only be used if an `googleplay_app_id` has been provided. Type: string | -| ios\_deep\_link *optional* | A deep link into the iOS app you're promoting. **Note**: Can only be used if an `ios_app_store_identifier` has been provided. Type: string | +--- -#### Example Request +## Full API Reference -`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards` +For the complete technical reference (all endpoints, parameters, and examples for Cards, Tweets, Media Library, Draft Tweets, Polls, Preroll, Conversation Cards, etc.), see the **[Creatives API Reference](/x-ads-api/creatives/reference)** page. -``` -{ - "name": "components create cards", - "components": [ - { - "type": "MEDIA", - "media_key": "3_1323490622599176192" - }, - { - "type": "BUTTON", - "label": { - "type": "ENUM", - "value": "INSTALL" - }, - "destination": { - "type": "APP", - "country_code": "US", - "googleplay_app_id": "com.twitter.android" - } - } - ] -} -``` -#### Example Response -``` -{ - "request": { - "params": { - "account_id": "18ce54d4x5t" - } - }, - "data": { - "name": "components create cards", - "components": [ - { - "type": "MEDIA", - "media_key": "3_1323490622599176192" - }, - { - "type": "BUTTON", - "label": { - "type": "ENUM", - "value": "INSTALL" - }, - "destination": { - "type": "APP", - "country_code": "US", - "googleplay_app_id": "com.twitter.android" - } + diff --git a/x-ads-api/creatives/reference.mdx b/x-ads-api/creatives/reference.mdx new file mode 100644 index 000000000..79e25b674 --- /dev/null +++ b/x-ads-api/creatives/reference.mdx @@ -0,0 +1,2939 @@ +--- +title: Creatives API Reference +sidebarTitle: API Reference +description: Complete technical reference for all Creatives endpoints in the X Ads API — Cards, Tweets, Media Library, Account Media, Draft Tweets, Polls, Preroll CTAs, Conversation Cards, Scheduled Tweets, and more. +keywords: ["creatives api", "ads creatives reference", "cards api", "tweet creatives", "media library api", "x ads api creatives"] +--- + +## API Reference + +### Account Media + + + +#### GET accounts/:account_id/account_media + +Retrieve details for some or all account media associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/account_media` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| account\_media\_ids *optional* | Scope the response to just the desired account media by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `3wpx` | +| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` | +| creative\_types *optional* | Scope the response to just the account media that match the specified creative types. More than one creative type may be specified by comma-separating enum values. Type: enum Possible values: `BANNER`, `BANNER_TABLET`, `INTERSTITIAL`, `INTERSTITIAL_LANDSCAPE`, `INTERSTITIAL_LANDSCAPE_TABLET`, `INTERSTITIAL_TABLET`, `MEDIUM_RECTANGLE`, `PREROLL`, `VAST_PREROLL` | +| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/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 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/account_media?account_media_ids=3wpx` + +#### Example Response +``` +{ + "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 a specific account media object associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| account\_media\_id *required* | A reference to the account media you are operating with in the request. Type: string Example: `2pnfd` | +| 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/account_media/2pnfd` + +#### Example Response +``` +{ + "request": { + "params": { + "account_media_id": "2pnfd", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "video_id": null, + "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig", + "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", + "id": "2pnfd", + "created_at": "2017-07-28T01:44:41Z", + "updated_at": "2017-07-28T01:44:41Z", + "deleted": false + } +} +``` + +Delete the specified account media object belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| account\_media\_id *required* | A reference to the account media you are operating with in the request. Type: string Example: `2pnfd` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd` + +#### Example Response +``` +{ + "data": { + "video_id": null, + "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig", + "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", + "id": "2pnfd", + "created_at": "2017-07-28T01:44:41Z", + "updated_at": "2017-08-25T17:16:26Z", + "deleted": true + }, + "request": { + "params": { + "account_id": "18ce54d4x5t", + "account_media_id": "2pnfd" + } + } +} +``` + +### Cards + + + +**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets), or the [POST accounts/:account\_id/draft\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/draft-tweets#post-accounts-account-id-draft-tweets) endpoints. + +Retrieve details for some or all cards associated with the current account. + +**Note**: This only returns cards that were created using the POST accounts/:account\_id/cards endpoint. Cards created using other endpoints are not returned. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_types *optional* | Scope the response to just the desired card types by specifying a comma-separated list of enum values. Type: enum Possible values: `IMAGE_APP`, `IMAGE_CAROUSEL_APP`, `IMAGE_CAROUSEL_WEBSITE`, `IMAGE_MULTI_DEST_CAROUSEL_WEBSITE`, `IMAGE_WEBSITE`, `MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE`, `VIDEO_APP`, `VIDEO_CAROUSEL_APP`, `VIDEO_CAROUSEL_WEBSITE`, `VIDEO_MULTI_DEST_CAROUSEL_WEBSITE`, `VIDEO_WEBSITE` | +| card\_id *optional* | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card IDs may be provided. Type: string Example: `1044294149527166979,1044301099031658496` | +| card\_uris *optional* | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: `card://1044294149527166979,card://1044301099031658496` | +| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` | +| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| include\_legacy\_cards *optional* | Include legacy website and app cards in the response. Legacy cards are those whose resource URL has the following format: accounts/:account\_id/cards/:card\_type. See [this developer forum post](https://devcommunity.x.com/t/new-cards-endpoints-and-carousel-ads/145782/6) for additional context. Type: boolean Default: `false` Possible values: `true`, `false` | +| q *optional* | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `dtc` | +| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/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` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1` + +#### Example Response +``` +{ + "request": { + "params": { + "count": 1, + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": "8wzvldqtc", + "data": [ + { + "name": "deep link", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1073727809120419840", + "3_1075096386931052545" + ] + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ], + "created_at": "2020-10-28T20:47:52Z", + "card_uri": "card://1321554298900107264", + "id": "1321554298900107264", + "updated_at": "2020-10-28T20:47:52Z", + "deleted": false, + "card_type": "IMAGE_CAROUSEL_APP" + } + ] +} +``` + +Retrieve details for a single card associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/:card_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id *required* | The id of the cards. Type: string Example: `1044294149527166979` | +| 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/cards/1321554298900107264` + +#### Example Response +``` +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "card_id": "1321554298900107264" + } + }, + "data": [ + { + "name": "deep link", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1073727809120419840", + "3_1075096386931052545" + ] + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ], + "created_at": "2020-10-28T20:47:52Z", + "card_uri": "card://1321554298900107264", + "id": "1321554298900107264", + "updated_at": "2020-10-28T20:47:52Z", + "deleted": false, + "card_type": "IMAGE_CAROUSEL_APP" + } + ] +} +``` +#### POST accounts/:account_id/cards + +Create a new card associated to the specified account. + +Card create requests only accept JSON POST bodies. The `Content-Type` must be set to `application/json`. + +See our [Carousels Guide](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/carousels) for a detailed usage example. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards` + +#### Parameters + +The JSON POST body must include a card `name` and an array of `components`. Components are represented as objects and describe the advertiser-facing attributes of the card. + +The following example shows the general structure of the payload (but includes non-working information). + +``` +{ + "name": "some name", + "components": [ + { + "type": "TYPE_ENUM", + "key": "value" + } + ] +} +``` + +Additional information on components below. + +| 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| name *required* | The name for the card. Maximum length: 80 characters. Type: string Example: `component based card` | +| components *sometimes required* | Describes the components to use to create the card. Additional information below. Cannot be specified along with `slides`. **Note**: The order of the components is important. Type: array of objects | +| slides *sometimes required* | Use this array of array to create Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with `components`. **Note**: The order of each slide is important. Type: array of array | + +#### Components + +Every component must include a `type` field which determines the object's schema. The Ads API supports the following component types, grouped into media- and description-based components. + +- Media: +- `MEDIA`: single video or image +- `SWIPEABLE_MEDIA`: between 2-6 videos or images +- Description: +- `DETAILS` +- `BUTTON` + +Each component has a set of required fields (in addition to the `type` key). These are listed in the following table. + +| Component `type` | Field | Value type | +| :--- | :--- | :--- | +| `MEDIA` | `media_key` | string | +| `SWIPEABLE_MEDIA` | `media_keys` | array of strings | +| `DETAILS` | `title` `destination` | string object | +| `BUTTON` | `label` `destination` | object object | + +The following is an example of a `BUTTON` component in the context of the `components` array (intentionally omitting the `name` key). (The ellipses indicate places where more information would need to be specified.) + +``` +{ + "components": [ + { + "type": "BUTTON", + "label": { + ... + }, + "destination": { + ... + } + } + ] +} +``` + +The order in which the component objects are specified defines the top-to-bottom order in which they will be rendered. Cards must be created using one media-based component and either a `DETAILS` or `BUTTON` component. Description-based components are rendered under media and have associated destinations, either URLs or mobile apps. + +**Label** + +Labels define the text shown on buttons and, therefore, only apply to the `BUTTON` component. Label objects have two required keys: `type` and `value`. The `type` must be set to `ENUM` and the `value` can be one of: `BOOK`, `CONNECT`, `INSTALL`, `OPEN`, `ORDER`, `PLAY`, or `SHOP`. + +Building on the previous example, the following shows the `label` object within the `BUTTON` component. + +``` +{ + "components": [ + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "INSTALL" + }, + "destination": { + ... + } + } + ] +} +``` + +**Destination** + +Destinations are where advertisers intend to take users. They are always required within `DETAILS` or `BUTTON` components. There are two destination types: `WEBSITE` or `APP`. + +**Note**: Website destinations can only be used with `DETAILS` components and app destinations can only be used with `BUTTON` components. + +**Website Destination** + +| Name | Description | +| :--- | :--- | +| type *required* | The destination type, which determines its schema. Type: enum Possible values: `WEBSITE` | +| url *required* | The URL of the website to redirect a user to. Type: string Example: `https://devcommunity.x.com/c/advertiser-api` | + +**App Destination** + +| Name | Description | +| :--- | :--- | +| type *required* | The destination type, which determines its schema. Type: enum Possible values: `APP` | +| country\_code *required* | The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) two-letter code for the country where the app is sold. Type: string Example: `US` | +| googleplay\_app\_id *sometimes required* | The Google Play application package name. **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `com.twitter.android` | +| ios\_app\_store\_identifier *sometimes required* | The iOS app store identifier. **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `333903271` | +| googleplay\_deep\_link *optional* | A deep link into the Android app you're promoting. **Note**: Can only be used if an `googleplay_app_id` has been provided. Type: string | +| ios\_deep\_link *optional* | A deep link into the iOS app you're promoting. **Note**: Can only be used if an `ios_app_store_identifier` has been provided. Type: string | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards` + +``` +{ + "name": "components create cards", + "components": [ + { + "type": "MEDIA", + "media_key": "3_1323490622599176192" + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "INSTALL" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android" + } + } + ] +} +``` +#### Example Response +``` +{ + "request": { + "params": { + "account_id": "18ce54d4x5t" + } + }, + "data": { + "name": "components create cards", + "components": [ + { + "type": "MEDIA", + "media_key": "3_1323490622599176192" + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "INSTALL" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android" + } + } + ], + "created_at": "2020-11-11T05:42:25Z", + "card_uri": "card://1326399865065238531", + "id": "1321554298900107264", + "updated_at": "2020-11-11T05:42:25Z", + "deleted": false, + "card_type": "IMAGE_APP" + } +} +``` + +Update the specified associated with the current account. + +Card edit requests only accept JSON POST bodies. The `Content-Type` must be set to `application/json`. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264` + +#### Parameters + +The JSON POST body must include the parameters that will be updated. The request will **replace** each field with the parameters specified within the payload. Components are represented as objects and describe the advertiser-facing attributes of the card. + +The following example shows the general structure of the payload (but includes non-working information). + +``` +{ + "name": "some name", + "components": [ + { + "type": "TYPE_ENUM", + "key": "value" + } + ] +} +``` + +Additional information on components and slides in **POST accounts/:account\_id/cards**. + +| 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| name *optional* | The name for the card. Maximum length: 80 characters. Type: string Example: `component based card` | +| components *optional* | Describes the components to use to update the card. Additional information below. Cannot be specified along with `slides`. **Note**: The order of the components is important. Type: array of objects | +| slides *optional* | Use this array of array to update Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with `components`. **Note**: The order of each slide is important. Type: array of array | + +#### Example Request + +This example updates both the name and removes one of the media\_keys from the components field from the example above. + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264` + +``` +{ + "name": "changed name", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1075096386931052545" + ] + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ] +} +``` +#### Example Response +``` +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "card_id": "1321554298900107264" + } + }, + "data": [ + { + "name": "changed name", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1075096386931052545" + ] + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ], + "created_at": "2020-10-28T20:47:52Z", + "card_uri": "card://1321554298900107264", + "id": "1321554298900107264", + "updated_at": "2020-10-29T20:47:52Z", + "deleted": false, + "card_type": "IMAGE_CAROUSEL_APP" + } + ] +} +``` + +Delete the specified card belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/:card_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id *required* | The id of the card to be deleted. Type: string Example: `1044294149527166979` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264` + +#### Example Response +``` +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "card_id": "1321554298900107264" + } + }, + "data": [ + { + "name": "deep link", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1073727809120419840", + "3_1075096386931052545" + ] + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ], + "created_at": "2020-10-28T20:47:52Z", + "card_uri": "card://1321554298900107264", + "id": "1321554298900107264", + "updated_at": "2020-10-29T20:47:52Z", + "deleted": true, + "card_type": "IMAGE_CAROUSEL_APP" + } + ] +} +``` + +### Cards Fetch + + + +Retrieve multiple cards, by `card_uri`, associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/all` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_uris *required* | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: `card://1044294149527166979,card://1044301099031658496` | +| 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/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496` + +#### Example Response +``` +{ + "request": { + "params": { + "card_uris": [ + "card://1044294149527166979", + "card://1044301099031658496" + ], + "account_id": "18ce54d4x5t" + } + }, + "data": [ + { + "name": "X App", + "googleplay_app_id": "com.twitter.android", + "image_display_height": "836", + "country_code": "US", + "id": "692xn", + "wide_app_image": "https://pbs.twimg.com/media/Dc263l9VwAAAeEH.jpg", + "created_at": "2018-09-24T18:35:01Z", + "image_display_width": "1600", + "card_uri": "card://1044294149527166979", + "updated_at": "2018-09-24T18:35:01Z", + "app_cta": "INSTALL", + "deleted": false, + "card_type": "IMAGE_APP_DOWNLOAD" + }, + { + "video_poster_height": "9", + "name": "Developer Platform", + "website_shortened_url": "https://t.co/zadeUSVD18", + "video_height": "9", + "video_url": "https://video.twimg.com/amplify_video/vmap/991374284135137280.vmap", + "content_duration_seconds": "24", + "video_owner_id": "756201191646691328", + "video_content_id": "13_991374284135137280", + "website_display_url": "developer.x.com", + "id": "6933h", + "video_width": "16", + "video_hls_url": "https://video.twimg.com/amplify_video/991374284135137280/pl/sQrBsE9mFvNep9Cx.m3u8?tag=2", + "website_dest_url": "https://developer.x.com", + "created_at": "2018-09-24T19:02:38Z", + "card_uri": "card://1044301099031658496", + "title": "Developer Platform", + "website_url": "https://developer.x.com", + "updated_at": "2018-09-24T19:02:38Z", + "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/991374284135137280/img/YbbGQHvWRjoFgrLz.jpg", + "video_poster_width": "16", + "deleted": false, + "card_type": "VIDEO_WEBSITE" + } + ] +} +``` + +Retrieve a specific card, by `card_id`, associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id *required* | A reference to the card you are operating with in the request. Type: string Example: `508pf` | +| 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/cards/all/508pf` + +#### Example Response +``` +{ + "request": { + "params": { + "card_id": "508pf", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "video_poster_height": "9", + "name": "video website card", + "video_height": "9", + "video_url": "https://video.twimg.com/amplify_video/vmap/867520357225418752.vmap", + "content_duration_seconds": "21", + "video_owner_id": "756201191646691328", + "video_content_id": "13_867520357225418752", + "website_display_url": "developer.x.com", + "id": "508pf", + "video_width": "16", + "video_hls_url": "https://video.twimg.com/amplify_video/867520357225418752/pl/TPHeH5ZlHFCa2TeJ.m3u8", + "website_dest_url": "https://developer.x.com/en/docs/ads/creatives/api-reference/video-website#post-accounts-account-id-cards-video-website", + "created_at": "2017-11-10T09:00:35Z", + "card_uri": "card://928910245920829440", + "title": "VWC", + "website_url": "https://t.co/F81hp59pUF", + "updated_at": "2018-01-05T05:43:31Z", + "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/867520357225418752/img/E3pnXM0sCKnRsFih.jpg", + "video_poster_width": "16", + "deleted": false, + "card_type": "VIDEO_WEBSITE" + } +} +``` + +### Draft Tweets + + + +#### GET accounts/:account_id/draft_tweets + +Retrieve details for some or all Draft Tweets associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` | +| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `c-jh1g0ryb` | +| user\_id *optional* | Specify the user to retrieve Draft Tweets for. Defaults to the `FULL` promotable user on the account when not set. Type: string Example: `756201191646691328` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1` + +#### Example Response +``` +{ + "request": { + "params": { + "count": 1 + } + }, + "data": [ + { + "name" null, + "text": "hello, world", + "user_id": "756201191646691328", + "id": "994791681219231744", + "nullcast": true, + "created_at": "2018-05-11T04:09:53Z", + "card_uri": null, + "updated_at": "2018-05-11T04:09:53Z", + "media_keys": [] + } + ], + "next_cursor": "c-jh1g0ryb" +} +``` + +Retrieve a specific Draft Tweet associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| draft\_tweet\_id *required* | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `994788364334325760` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760` + +#### Example Response +``` +{ + "request": { + "params": { + "draft_tweet_id": "994788364334325760" + } + }, + "data": { + "name": null, + "text": "#TwitterDev", + "user_id": "756201191646691328", + "id": "994788364334325760", + "nullcast": true, + "created_at": "2018-05-11T03:56:42Z", + "card_uri": "card://958225772740714496", + "updated_at": "2018-05-11T03:56:42Z", + "media_keys": [] + } +} +``` +#### POST accounts/:account_id/draft_tweets + +Create a Draft Tweet for the account's full promotable user (default) or the user specified in the `as_user_id` parameter. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| as\_user\_id *required* | The user ID of the advertiser on behalf of whom you are posting the Tweet. The advertiser must grant your handle (or handles) access to their ads account via [ads.x.com](https://ads.x.com/). This permission allows you to call the API using the OAuth tokens of your own handle rather than the advertiser's. Type: string Example: `756201191646691328` | +| text *sometimes required* | The text of your status update. Required if no `media_keys` are specified. Type: string Example: `Just setting up my X.` | +| card\_uri *optional* | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. Type: string Example: `card://960880280705392541` | +| media\_keys *optional* | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). Type: string Example: `13_1153584529292270722` | +| nullcast *optional* | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Default: `true` Possible values: `true`, `false` | +| name *optional* | The name for the Draft Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.` + +#### Example Response +``` +{ + "request": { + "params": { + "text": "Just setting up my X.", + "as_user_id": "756201191646691328" + } + }, + "data": { + "name": null, + "text": "Just setting up my X.", + "user_id": "756201191646691328", + "id": "994747471329873920", + "nullcast": true, + "created_at": "2018-05-11T01:14:13Z", + "card_uri": null, + "updated_at": "2018-05-11T01:14:13Z", + "media_keys": [] + } +} +``` + +Update the specified Draft Tweet belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| draft\_tweet\_id *required* | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `994747471329873920` | +| card\_uri *optional* | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `card://970582057284129151` | +| media\_keys *optional* | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `13_1153584529292270722` | +| nullcast *optional* | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Possible values: `true`, `false` | +| text *optional* | The text of your status update. Type: string Example: `just setting up my twttr` | +| name *optional* | The name for the Draft Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr` + +#### Example Response +``` +{ + "request": { + "params": { + "draft_tweet_id": 994747471329873920, + "text": "just setting up my twttr" + } + }, + "data": { + "name": null, + "text": "just setting up my twttr", + "user_id": "756201191646691328", + "id": "994747471329873920", + "nullcast": true, + "created_at": "2018-05-11T01:14:13Z", + "card_uri": null, + "updated_at": "2018-05-11T01:16:59Z", + "media_keys": [] + } +} +``` + +Permanently delete the specified Draft Tweet belonging to the current account. + +**Note**: We **strongly** recommend deleting drafts once a Tweet or Scheduled Tweet has been created using its metadata. + +**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted Draft Tweets. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| draft\_tweet\_id *required* | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `994787835663155200` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200` + +#### Example Response +``` +{ + "request": { + "params": { + "draft_tweet_id": "994787835663155200" + } + }, + "data": { + "name": null, + "text": "hello, world", + "user_id": "756201191646691328", + "id": "994787835663155200", + "nullcast": true, + "status": "DELETED", + "created_at": "2018-05-11T03:54:36Z", + "card_uri": null, + "updated_at": "2018-05-11T04:07:31Z", + "media_keys": [] + } +} +``` +#### POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id + +Preview a Draft Tweet on a mobile device. + +A successful request sends a notification to every device the authenticated user is logged in to. Clicking on the notification opens a timeline that allows the user to see and interact with the Draft Tweet, enabling them to test auto-play, volume, fullscreen, video website card docking, and other behaviors. + +**Note**: On-device previews are only visible to the user who receives the notification. + +**Note**: Notifications only get sent to X official apps. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| draft\_tweet\_id *required* | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `996132315829948416` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416` + +#### Example Response +``` +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "draft_tweet_id": "996132315829948416" + } + }, + "message": "See @apimctestface's notifications in the X app to preview your Tweet." +} +``` + +### Image Conversation Cards + + + +**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), or [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets) endpoints. + +#### GET accounts/:account_id/cards/image_conversation + +Retrieve details for some or all image conversation cards associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_ids *optional* | Scope the response to just the desired image conversation cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `59woh` | +| 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](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| q *optional* | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `night` | +| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/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 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/cards/image_conversation?card_ids=59woh` + +#### Example Response +``` +{ + "request": { + "params": { + "card_type": "image_conversation", + "card_ids": [ + "59woh" + ], + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "name": "image conversation card", + "first_cta": "#moon", + "image_display_height": "670", + "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg", + "thank_you_text": "thanks", + "id": "59woh", + "first_cta_tweet": "stars", + "media_key": "3_957113581522141184", + "created_at": "2018-01-27T04:58:42Z", + "image_display_width": "1280", + "card_uri": "card://923498485702009837", + "title": "Full moon", + "updated_at": "2018-01-27T04:58:42Z", + "deleted": false, + "card_type": "IMAGE_CONVERSATION" + } + ] +} +``` + +Retrieve a specific image conversation card associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id *required* | A reference to the image conversation card you are operating with in the request. Type: string Example: `59woh` | +| 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/cards/image_conversation/59woh` + +#### Example Response +``` +{ + "request": { + "params": { + "card_type": "image_conversation", + "card_id": "59woh", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "name": "image conversation card", + "first_cta": "#moon", + "image_display_height": "670", + "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg", + "thank_you_text": "thanks", + "id": "59woh", + "first_cta_tweet": "stars", + "media_key": "3_957113581522141184", + "created_at": "2018-01-27T04:58:42Z", + "image_display_width": "1280", + "card_uri": "card://923498485702009837", + "title": "Full moon", + "updated_at": "2018-01-27T04:58:42Z", + "deleted": false, + "card_type": "IMAGE_CONVERSATION" + } +} +``` +#### POST accounts/:account_id/cards/image_conversation + +Create a new image conversation card associated with the specified account. + +See [Uploading Media](https://developer.x.com/rest/public/uploading-media) for useful information on uploading images to our endpoints. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| first\_cta *required* | The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareNow` | +| first\_cta\_tweet *required* | The Tweet text to be used when the first CTA is clicked. Type: string Example: `I Heart @AdsAPI` | +| media\_key *required* | The media key for an image to be used in this card. **Note**: The image must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string Example: `3_1151345051104991073` | +| name *required* | The name for the card. Type: string Example: `image conversation card` | +| thank\_you\_text *required* | The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: `Thank you` | +| second\_cta *sometimes required* | The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string **Note**: Required if `title` is `not` set. Example: `#ShareAgain` | +| second\_cta\_tweet *sometimes required* | The Tweet text to be used when the second CTA is clicked. **Note**: Required if `second_cta` is set. Type: string Example: `I Heart @AdsAPI Again` | +| title *sometimes required* | The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters. Type: string **Note**: Required if `second_cta` is `not` set. Example: `Start a conversation` | +| third\_cta *optional* | The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareMore` | +| third\_cta\_tweet *sometimes required* | The Tweet text to be used when the third CTA is clicked. Type: string **Note**: Required if `third_cta` is set. Example: `I Heart @TwitterDev` | +| fourth\_cta *optional* | The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareExtra` | +| fourth\_cta\_tweet *sometimes required* | The Tweet text to be used when the fourth CTA is clicked. Type: string **Note**: Required if `fourth_cta` is set. Example: `I Heart @TwitterDev Again` | +| unlocked\_image\_media\_key *optional* | A `media_key` of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. **Note**: The image must be in the account's media library. **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: `3_883112887618682880` | +| thank\_you\_url *optional* | The URL to be displayed with the thank you text. Type: string Example: `https://example.com/thankyou` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?media_key=3_957113581522141184&name=image conversation card&first_cta=#moon&first_cta_tweet=stars&thank_you_text=thanks&title=Full moon` + +#### Example Response +``` +{ + "data": { + "name": "image conversation card", + "first_cta": "#moon", + "image_display_height": "670", + "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg", + "thank_you_text": "thanks", + "id": "59woh", + "first_cta_tweet": "stars", + "media_key": "3_957113581522141184", + "created_at": "2018-01-27T04:58:42Z", + "image_display_width": "1280", + "card_uri": "card://923498485702009837", + "title": "Full moon", + "updated_at": "2018-01-27T04:58:42Z", + "deleted": false, + "card_type": "IMAGE_CONVERSATION" + }, + "request": { + "params": { + "name": "image conversation card", + "first_cta": "#moon", + "image_display_height": "670", + "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg", + "thank_you_text": "thanks", + "media_key": "3_957113581522141184", + "account_id": "18ce54d4x5t", + "first_cta_tweet": "stars", + "image_display_width": "1280", + "title": "Full moon", + "card_type": "IMAGE_CONVERSATION" + } + } +} +``` + +Update the specified image conversation card belonging to the current account. + +See [Uploading Media](https://developer.x.com/rest/public/uploading-media) for useful information on uploading images to our endpoints. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id *required* | A reference to the image conversation card you are operating with in the request. Type: string Example: `4i0qg` | +| first\_cta *optional* | The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareNow` | +| first\_cta\_tweet *optional* | The Tweet text to be used when the first CTA is clicked. Type: string Example: `I Heart @AdsAPI` | +| second\_cta *optional* | The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string **Note**: Required if `title` is `not` set. Example: `#ShareAgain` | +| second\_cta\_tweet *optional* | The Tweet text to be used when the second CTA is clicked. **Note**: Required if `second_cta` is set. Type: string Example: `I Heart @AdsAPI Again` | +| third\_cta *optional* | The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareMore` | +| third\_cta\_tweet *optional* | The Tweet text to be used when the third CTA is clicked. Type: string **Note**: Required if `third_cta` is set. Example: `I Heart @TwitterDev` | +| fourth\_cta *optional* | The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareExtra` | +| fourth\_cta\_tweet *optional* | The Tweet text to be used when the fourth CTA is clicked. Type: string **Note**: Required if `fourth_cta` is set. Example: `I Heart @TwitterDev Again` | +| media\_key *optional* | The media key for an image to be used in this card. **Note**: The image must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string Example: `3_1151345051104991073` | +| name *optional* | The name for the card. Type: string Example: `moon card` | +| thank\_you\_text *optional* | The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: `Thank you` | +| thank\_you\_url *optional* | The URL to be displayed with the thank you text. Type: string Example: `https://example.com/thankyou` | +| title *optional* | The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters. Type: string **Note**: Required if `second_cta` is `not` set. Example: `Start a conversation` | +| unlocked\_image\_media\_key *optional* | A `media_key` of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. **Note**: The image must be in the account's media library. **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: `3_883112887618682880` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card` + +#### Example Response +``` +{ + "data": { + "name": "moon card", + "id": "59woh", + "created_at": "2018-01-27T04:58:42Z", + "card_uri": "card://923498485702009837", + "updated_at": "2018-01-29T21:04:39Z", + "deleted": false, + "card_type": "IMAGE_CONVERSATION" + }, + "request": { + "params": { + "account_id": "18ce54d4x5t", + "card_type": "IMAGE_CONVERSATION", + "card_id": "59woh", + "name": "moon card" + } + } +} +``` + +Permanently delete the specified image conversation card belonging to the current account. + +**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted cards. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id *required* | A reference to the image conversation card you are operating with in the request. Type: string Example: `4i0qe` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe` + +#### Example Response +``` +{ + "data": { + "name": "image conversation card", + "id": "4i0qe", + "created_at": "2017-07-07T00:03:01Z", + "updated_at": "2017-08-23T13:26:23Z", + "deleted": true, + "card_type": "IMAGE_CONVERSATION" + }, + "request": { + "params": { + "card_id": "4i0qe", + "card_type": "image_conversation", + "account_id": "18ce54d4x5t" + } + } +} +``` + +### Media Library + + + +#### GET accounts/:account_id/media_library + +Retrieve details for some or all media library objects associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `20` Min, Max: `1`, `50` | +| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `c-1` | +| media\_type *optional* | Scope the response to just the desired media type. Type: enum Possible values: `GIF`, `IMAGE`, `VIDEO` | +| q *optional* | An optional query to scope resource by `name`, `title`, `file_name`, and `description` fields. **Note**: This performs case-insensitive *term* matching. Type: string Min, Max length: `1`, `255` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?count=1` + +#### Example Response +``` +{ + "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 a specific media library object associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| media\_key *required* | A reference to the media library object you are operating with in the request. Type: string Example: `13_909110614026444802` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802` + +#### Example Response +``` +{ + "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 + } +} +``` + +Associate a media object with the current account. For additional details, please see our [Media Library guide](https://developer.x.com/en/docs/ads/creatives/guides/media-library). + +**Note**: When adding a video with the `AMPLIFY_VIDEO` media category to the Media Library, it is automatically available as a `PREROLL` [account\_media](https://developer.x.com/en/docs/ads/creatives/api-reference/account-media#get-accounts-account-id-account-media) asset. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| media\_key *required* | The `media_key` for the uploaded content. A `media_key` is returned in the POST media/upload response when a `media_category` is specified. Type: string Example: `3_931236738554519552` | +| description *optional* | The description that appears under the video when Tweeted. Maximum length: 200 characters. This is not rendered in the Tweet by default. To display the video's `description`, use the `video_description` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `This is the description under the video.` | +| file\_name *optional* | The file name for the media library object. Maximum length: 255. The file name can be seen in the media detail of every media asset in the Media Library UI on ads.x.com. This will be empty when the `file_name` is not set. Type: string Example: `coffee.jpeg` | +| name *optional* | The name for the media library object. Maximum length: 100. This is the label under every media asset in the Media Library UI on ads.x.com. The label will be "Untitled" when the `name` is not set. Type: string Example: `Latte` | +| poster\_media\_key *optional* | Specify a poster image for the video using the `media_key` of an uploaded image. If not specified, the first frame will be used. **Note**: Can only be used with videos. Type: string Example: `3_890599134483242005` | +| title *optional* | The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters. This is not rendered in the Tweet by default. To display the video's `title`, use the `video_title` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `Video title` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552` + +#### Example Response +``` +{ + "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 + } +} +``` + +Update the specified media library object belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| media\_key *required* | A reference to the media library object you are operating with in the request. Type: string Example: `16_844800354743074820` | +| description *optional* | The description that appears under the video when Tweeted. Maximum length: 200 characters. This is not rendered in the Tweet by default. To display the video's `description`, use the `video_description` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `This is the description under the video.` | +| file\_name *optional* | The file name for the media library object. Maximum length: 255. The file name can be seen in the media detail of every media asset in the Media Library UI on ads.x.com. This will be empty when the `file_name` is not set. Type: string Example: `coffee.jpeg` | +| name *optional* | The name for the media library object. Maximum length: 100. This is the label under every media asset in the Media Library UI on ads.x.com. The label will be "Untitled" when the `name` is not set. Type: string Example: `Latte` | +| poster\_media\_key *optional* | Specify a poster image for the video using the `media_key` of an uploaded image. **Note**: Can only be used with videos. Type: string Example: `3_885003359340375465` | +| title *optional* | The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters. This is not rendered in the Tweet by default. To display the video's `title`, use the `video_title` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `Video title` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space` + +#### Example Response +``` +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "media_key": "16_844800354743074820", + "title": "cat GIF", + "description": "in space" + } + }, + "data": { + "tweeted": true, + "duration": null, + "name": null, + "file_name": null, + "description": "in space", + "media_url": "https://video.twimg.com/tweet_video/C7lVclqVwAQqTCZ.mp4", + "media_category": "TWEET_GIF", + "poster_media_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg", + "poster_media_key": "3_844800354743074820", + "media_key": "16_844800354743074820", + "created_at": "2017-10-20T09:51:54Z", + "media_status": "TRANSCODE_COMPLETED", + "title": "cat GIF", + "media_type": "GIF", + "aspect_ratio": "125:79", + "updated_at": "2017-10-23T06:37:56Z", + "deleted": false + } +} +``` + +Delete the specified media library object belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| media\_key *required* | A reference to the media library object you are operating with in the request. Type: string Example: `7_860318603387600896` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896` + +#### Example Response +``` +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "media_key": "7_860318603387600896" + } + }, + "data": { + "tweeted": true, + "duration": 14330, + "name": "mountains-on-ads.x.com", + "file_name": "mountains.mp4", + "description": "", + "media_url": "https://video.twimg.com/ext_tw_video/860318603387600896/pu/vid/1280x720/xI3DbvWKxdvICsFW.mp4", + "media_category": "TWEET_VIDEO", + "poster_media_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg", + "poster_media_key": "3_860318839740915712", + "media_key": "7_860318603387600896", + "created_at": "2017-05-05T02:21:53Z", + "media_status": "TRANSCODE_COMPLETED", + "title": "uploaded on ads.x.com", + "media_type": "VIDEO", + "aspect_ratio": "16:9", + "updated_at": "2017-05-05T02:26:58Z", + "deleted": true + } +} +``` + +### Poll Cards + + + +#### GET accounts/:account_id/cards/poll + +Retrieve details for some or all poll cards associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/poll` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_ids *optional* | Scope the response to just the desired poll cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `57i77` | +| 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](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| q *optional* | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `night` | +| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/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 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/cards/poll?card_ids=57i77` + +#### Example Response +``` +{ + "request": { + "params": { + "card_type": "poll", + "card_ids": [ + "57i77" + ], + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "video_poster_height": "9", + "name": "best coast poll", + "start_time": "2018-01-09T04:51:34Z", + "first_choice": "East", + "video_height": "9", + "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap", + "content_duration_seconds": "8", + "second_choice": "West", + "end_time": "2018-01-16T04:51:34Z", + "id": "57i77", + "video_width": "16", + "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4", + "created_at": "2018-01-09T04:51:34Z", + "duration_in_minutes": "10080", + "card_uri": "card://950590850777497601", + "updated_at": "2018-01-09T04:51:34Z", + "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg", + "video_poster_width": "16", + "deleted": false, + "card_type": "VIDEO_POLLS" + } + ] +} +``` + +Retrieve a specific poll card associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id *required* | A reference to the poll card you are operating with in the request. Type: string Example: `57i8t` | +| 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/cards/poll/57i8t` + +#### Example Response +``` +{ + "request": { + "params": { + "card_type": "poll", + "card_id": "57i8t", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "name": "text only poll", + "start_time": "2018-01-09T05:03:05Z", + "first_choice": "Morning", + "second_choice": "Evening", + "end_time": "2018-01-11T05:03:05Z", + "id": "57i8t", + "created_at": "2018-01-09T05:03:05Z", + "duration_in_minutes": "2880", + "card_uri": "card://950593749658189824", + "updated_at": "2018-01-09T05:03:05Z", + "deleted": false, + "card_type": "TEXT_POLLS" + } +} +``` +#### POST accounts/:account_id/cards/poll + +Create a new poll card associated with the specified account. This endpoint supports creating poll cards with either an image, a video, or no media. Polls with media are referred to as Media Forward Polls. + +**Note**: The Media Forward Polls product is in beta and requires the `PROMOTED_MEDIA_POLLS` account feature. + +**Note**: It is not possible to update (PUT) poll cards. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/poll` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| duration\_in\_minutes *required* | The amount of time (in minutes) the poll will remain open. After the specified `duration_in_minutes`, the poll will close and votes will no longer be accepted. This corresponds to `end_time` in the response. **Note**: This starts as soon as the card is created and not when it is added to a Tweet. Type: int Min, Max: `5`, `10080` | +| first\_choice *required* | The first poll choice. Maximum length: 25 characters. Type: string Example: `One` | +| name *required* | The name for the card. Type: string Example: `poll card` | +| second\_choice *required* | The second poll choice.Maximum length: 25 characters. Type: string Example: `Two` | +| fourth\_choice *optional* | The fourth poll choice. Maximum length: 25 characters. **Note**: The first, second, and third choices must be set when using this parameter. Type: string Example: `Four` | +| media\_key *optional* | The `media_key` of a media library image or video which will be used in this card. This is a write-only field. In the response, the API will provide a X URL for this media. **Note**: The image or video must be in the account's media library. **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. | +| third\_choice *optional* | The third poll choice. Maximum length: 25 characters. **Note**: The first and second choices must be set when using this parameter. Type: string Example: `Three` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?duration_in_minutes=10080&first_choice=East&second_choice=West&media_key=13_950589518557540353&name=best coast poll` + +#### Example Response +``` +{ + "request": { + "params": { + "first_choice": "East", + "name": "best coast poll", + "second_choice": "West", + "media_key": "13_950589518557540353", + "duration_in_minutes": 10080 + } + }, + "data": { + "video_poster_height": "9", + "name": "best coast poll", + "start_time": "2018-01-09T04:51:34Z", + "first_choice": "East", + "video_height": "9", + "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap", + "content_duration_seconds": "8", + "second_choice": "West", + "end_time": "2018-01-16T04:51:34Z", + "id": "57i77", + "video_width": "16", + "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4", + "created_at": "2018-01-09T04:51:34Z", + "duration_in_minutes": "10080", + "card_uri": "card://950590850777497601", + "updated_at": "2018-01-09T04:51:34Z", + "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg", + "video_poster_width": "16", + "deleted": false, + "card_type": "VIDEO_POLLS" + } +} +``` + +Permanently delete the specified poll card belonging to the current account. + +Note: This is a hard delete. As a result, it is not possible to retrieve deleted cards. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id *required* | A reference to the poll card you are operating with in the request. Type: string Example: `57i9t` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t` + +#### Example Response +``` +{ + "data": { + "name": "poll with image", + "start_time": "2018-01-09T05:10:51Z", + "id": "57i9t", + "created_at": "2018-01-09T05:10:51Z", + "updated_at": "2018-01-09T05:11:04Z", + "deleted": true, + "card_type": "IMAGE_POLLS" + }, + "request": { + "params": { + "card_id": "57i9t", + "card_type": "poll", + "account_id": "18ce54d4x5t" + } + } +} +``` + +### Preroll Call To Actions + + + +#### GET accounts/:account_id/preroll_call_to_actions + +Retrieve details for some or all preroll Call-To-Actions (CTAs) associated with line items under the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| line\_item\_ids *optional* | Scope the response to just the preroll CTAs associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `8v53k` | +| 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](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| preroll\_call\_to\_action\_ids *optional* | Scope the response to just the desired preroll CTAs by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `8f0` | +| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/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 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/preroll_call_to_actions?line_item_ids=8v53k` + +#### Example Response +``` +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "line_item_ids": [ + "8v53k" + ] + } + }, + "next_cursor": null, + "data": [ + { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "VISIT_SITE", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-07-07T19:28:40Z", + "deleted": false + } + ] +} +``` + +Retrieve a specific Call-to-Action (CTAs) associated with this account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| preroll\_call\_to\_action\_id *required* | A reference to the preroll call to action you are operating with in the request. Type: string Example: `8f0` | +| 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/preroll_call_to_actions/8f0` + +#### Example Response +``` +{ + "request": { + "params": { + "preroll_call_to_action_id": "8f0", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "VISIT_SITE", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-07-07T19:28:40Z", + "deleted": false + } +} +``` +#### POST accounts/:account_id/preroll_call_to_actions + +Set the optional Call-to-Action (CTA) for a `PREROLL_VIEWS` line item. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| call\_to\_action *required* | The CTA text for the displayed button within the ad. Type: enum Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW` | +| call\_to\_action\_url *required* | The URL to redirect the user to when the CTA button is clicked. Type: string Example: `https://www.x.com` | +| line\_item\_id *required* | A reference to the line item you are operating with in the request. Type: string Example: `8v53k` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_id=8v53k&call_to_action=VISIT_SITE&call_to_action_url=https://www.x.com` + +#### Example Response +``` +{ + "data": { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "VISIT_SITE", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-07-07T19:28:40Z", + "deleted": false + }, + "request": { + "params": { + "line_item_id": "8v53k", + "call_to_action": "VISIT_SITE", + "call_to_action_url": "https://www.x.com", + "account_id": "18ce54d4x5t" + } + } +} +``` + +Update the optional Call-to-Action (CTA) for a `PREROLL_VIEWS` line item. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| preroll\_call\_to\_action\_id *required* | A reference to the preroll CTA you are operating with in the request. Type: string Example: `8f0` | +| call\_to\_action *optional* | The CTA text for the displayed button within the ad. Type: enum Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW` | +| call\_to\_action\_url *optional* | The URL to redirect the user to when the CTA button is clicked. Type: string Example: `https://www.x.com` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW` + +#### Example Response +``` +{ + "data": { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "WATCH_NOW", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-09-09T05:51:26Z", + "deleted": false + }, + "request": { + "params": { + "preroll_call_to_action_id": "8f0", + "call_to_action": "WATCH_NOW", + "account_id": "18ce54d4x5t" + } + } +} +``` + +Delete the specified preroll Call-to-Action (CTA) belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| preroll\_call\_to\_action\_id *required* | A reference to the preroll CTA you are operating with in the request. Type: string Example: `8f0` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0` + +#### Example Response +``` +{ + "data": { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "VISIT_SITE", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-08-30T06:08:21Z", + "deleted": true + }, + "request": { + "params": { + "preroll_call_to_action_id": "8f0", + "account_id": "18ce54d4x5t" + } + } +} +``` + +### Scheduled Tweets + + + +#### GET accounts/:account_id/scheduled_tweets + +Retrieve details for some or all Scheduled Tweets associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` | +| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `c-j3cn6n40` | +| user\_id *optional* | Specify the user to retrieve Scheduled Tweets for. Defaults to the `FULL` promotable user on the account when not set. Type: long Example: `756201191646691328` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1` + +#### Example Response +``` +{ + "request": { + "params": { + "count": 1 + } + }, + "data": [ + { + "name": "test name", + "completed_at": "2017-06-18T22:00:05Z", + "text": "where you want to be", + "user_id": "756201191646691328", + "scheduled_status": "SUCCESS", + "id": "875828692081037312", + "nullcast": true, + "created_at": "2017-06-16T21:33:27Z", + "scheduled_at": "2017-06-18T22:00:00Z", + "card_uri": null, + "updated_at": "2017-06-19T18:02:20Z", + "tweet_id": "876560168963645440", + "media_keys": [] + } + ], + "next_cursor": "c-j41uw400" +} +``` + +Retrieve a specific Scheduled Tweet associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| scheduled\_tweet\_id *required* | A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `917438609065623552` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552` + +#### Example Response +``` +{ + "request": { + "params": { + "scheduled_tweet_id": "917438609065623552" + } + }, + "data": { + "name": null, + "completed_at": null, + "text": "", + "user_id": "756201191646691328", + "scheduled_status": "SCHEDULED", + "id": "917438609065623552", + "nullcast": true, + "created_at": "2017-10-09T17:16:24Z", + "scheduled_at": "2018-01-01T00:00:00Z", + "card_uri": null, + "updated_at": "2017-10-09T17:16:24Z", + "tweet_id": null, + "media_keys": [ + "3_917438348871983104" + ] + } +} +``` +#### POST accounts/:account_id/scheduled_tweets + +Create a Scheduled Tweet for the account's full promotable user (default) or the user specified in the `as_user_id` parameter. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| scheduled\_at *required* | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live). **Note**: Tweets can only be scheduled up to one year in the future. **Note**: Tweets should only be scheduled at minute-granularity; seconds will be ignored. Type: string Example: `2017-12-31T23:59:00Z` | +| as\_user\_id *required* | The user ID of the advertiser on behalf of whom you are posting the Tweet. The advertiser must grant your handle (or handles) access to their ads account via [ads.x.com](https://ads.x.com/). This permission allows you to call the API using the OAuth tokens of your own handle rather than the advertiser's. Type: long Example: `756201191646691328` | +| text *sometimes required* | The text of your status update. Required if no `media_keys` are specified. Type: string Example: `just setting up my twttr` | +| card\_uri *optional* | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. Type: string Example: `card://855591459410511943` | +| media\_keys *optional* | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). Type: string Example: `13_1153584529292270722` | +| nullcast *optional* | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Default: `true` Possible values: `true`, `false` | +| name *optional* | The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_keys=3_917438348871983104&scheduled_at=2018-01-01` + +#### Example Response +``` +{ + "request": { + "params": { + "media_keys": [ + "3_917438348871983104" + ], + "scheduled_at": "2018-01-01T00:00:00Z", + "as_user_id": 756201191646691328 + } + }, + "data": { + "name": null, + "completed_at": null, + "text": "", + "user_id": "756201191646691328", + "scheduled_status": "SCHEDULED", + "id": "917438609065623552", + "nullcast": true, + "created_at": "2017-10-09T17:16:24Z", + "scheduled_at": "2018-01-01T00:00:00Z", + "card_uri": null, + "updated_at": "2017-10-09T17:16:24Z", + "tweet_id": null, + "media_keys": [ + "3_917438348871983104" + ] + } +} +``` + +Update the specified Scheduled Tweet belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| scheduled\_tweet\_id *required* | A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `870321875435442177` | +| card\_uri *optional* | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `card://875146925316386347` | +| media\_keys *optional* | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `13_1153584529292270722` | +| nullcast *optional* | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Possible values: `true`, `false` | +| scheduled\_at *optional* | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live). Type: string Example: `2017-12-31T23:59:59Z` | +| text *optional* | The text of your status update. Type: string Example: `just setting up my twttr` | +| name *optional* | The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice` + +#### Example Response +``` +{ + "request": { + "params": { + "scheduled_tweet_id": "875057751231037440", + "text": "winter solstice" + } + }, + "data": { + "name": null, + "completed_at": null, + "scheduled_status": "SCHEDULED", + "text": "winter solstice", + "user_id": "756201191646691328", + "id": "875057751231037440", + "nullcast": true, + "created_at": "2017-06-14T18:30:00Z", + "scheduled_at": "2017-12-21T00:00:00Z", + "card_uri": null, + "updated_at": "2017-06-14T18:30:00Z", + "tweet_id": null, + "media_keys": [] + } +} +``` + +Permanently delete the specified Scheduled Tweet belonging to the current account. + +**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted Scheduled Tweets. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| scheduled\_tweet\_id *required* | A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `870321875435442177` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776` + +#### Example Response +``` +{ + "request": { + "params": { + "scheduled_tweet_id": 875064008595787776 + } + }, + "data": { + "name": null, + "completed_at": null, + "scheduled_status": "DELETED", + "text": "hello, world", + "user_id": "756201191646691328", + "id": "875064008595787776", + "nullcast": true, + "created_at": "2017-06-14T18:54:52Z", + "scheduled_at": "2017-06-15T00:00:00Z", + "card_uri": null, + "updated_at": "2017-06-14T19:01:16Z", + "tweet_id": null, + "media_keys": [] + } +} +``` + +### Tweet Previews + + + +#### GET accounts/:account_id/tweet_previews + +Preview published, scheduled, or draft Tweets. + +- Supports previewing *multiple* Tweets—up to 200—in a single API request +- Accurate, up-to-date rendering of Tweet layout and style +- Supports all the latest formats and card types +- Returns an iframe + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/tweet_previews` + +#### 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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| tweet\_ids *required* | A comma-separated list of identifiers. Up to 200 IDs may be provided. **Note**: The IDs should correspond to the specified `tweet_type`. For example, if a Scheduled Tweet ID is passed in and `tweet_type=PUBLISHED` is specified, a preview for that ID will not be returned. Type: long Example: `1122911801354510336,1102836745790316550` | +| tweet\_type *required* | The Tweet type for the specified `tweet_ids`. Type: enum Possible values: `DRAFT`, `PUBLISHED`, `SCHEDULED` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED` + +#### Example Response +``` +{ + "request": { + "params": { + "tweet_ids": [ + "1122911801354510336", + "1102836745790316550" + ], + "tweet_type": "PUBLISHED", + "account_id": "18ce54d4x5t" + } + }, + "data": [ + { + "tweet_id": "1122911801354510336", + "preview": "